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Preface 



The Microsoft Operating System/2 Windows Presentation Manager Refer- 
ence, Volumes 1, 2, and 3, is derived from the latest draft of the functional 
specification of the Windows Presentation Manager. Although this docu- 
mentation does not represent the final Windows Presentation Manager 
specification, it does provide a reasonable preview of the functionality you 
can expect from the final product. 

This documentation is preliminary in nature. The application program 
interface and other features of the Windows Presentation Manager 
described in this document are subject to change. It is strongly recom- 
mended that the documentation be read for informational purposes only. 
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Introduction 



1.1 Introduction and Guide to 

Windows Presentation Manager 



This section introduces Windows Presentation Manager to the end user. 

1.1.1 What is Presentation Manager? 

The Windows Presentation Manager is the presentation services com- 
ponent of the MS OS/2 operating system. Its features include: 

• the ability to view output from multiple applications on the 
display simultaneously 

• an enhanced User Interface to both MS OS/2 and application func- 
tions 

• programming interfaces which provide applications with sophisti- 
cated functions: 

• for generating and displaying Graphics and Alphanumerics 
data on a range of output devices including the display screen. 

• for handling Input devices such as mouse and keyboard 

• for Windowing data onto the display screen 

• for the provision of a User Interface which is both rich in func- 
tion and consistent across applications. 

Applications which run with the MS OS/2 kernel will also run when 
Presentation Manager is present. However, not all these applications can 
take advantage of the additional facilities provided by Presentation 
Manager. In particular, applications which attempt to access the display 
or input devices directly cannot share the screen concurrently with other 
applications and cannot use the Presentation Manager programming inter- 
faces. The applications which cannot take advantage of Presentation 
Manager are termed Non-Presentation Manager Applications. The sec- 
tion, “Running MS OS/2 Kernel Applications Under Presentation 
Manager”, defines the applications that may not be run in the Presenta- 
tion Manager screen group. 

1.1.2 Fundamental Features of 
Windows Presentation Manager 
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1.1. 2.1 User Interface Shell 

When the MS OS/2 system is started up with Windows Presentation 
Manager present, the display screen is initially occupied by the Presenta- 
tion Manager User Interface Shell. The Presentation Manager User Inter- 
face Shell replaces the simple User Interface Shell provided with the MS 
OS/2 kernel. It provides the following end-user functions: 



Start an Application 

The user is presented with a list of all the available applica- 
tions and can choose one to start. There is a ’command line’ 
option, which enables the user to start a program by enter- 
ing the command line in a manner consistent with MS OS/2. 

A means is provided for the user to update the list of of 
applications - adding or removing entries as desired - and 
updating the application profile for each of them. 

Switch to another Application 

The user can display all the applications which are running 
and can select which one to work with next. The list 
includes both Presentation Manager and non-Presentation 
Manager applications. 

Control of the Position and Size of Application Windows 

Each Presentation Manager application has one or more 
Windows on the screen. The User Interface Shell provides 
the user means of controlling the size and position of the 
windows visible on the screen. 

Control of the Printing functions. 

A menu is provided to give the user control over the Printing 
functions performed by Presentation Manager. 

Use of MS OS/2 file system 

An easy-to-use method of interacting with the MS OS/2 file 
system is provided, that allows the end-user to perform file 
commands such as copying or renaming files. 

Control functions 

Provides the user with a consistent and easy-to-use method 
of selecting defaults for various Presentation Manager 
parameters, e.g. the colour of empty space on the screen. 
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1.1.2. 2 Screen Appearance. 

As applications are started by the user they appear on the screen. The 
applications fall into two classes - Presentation Manager and Non- 
Presentation Manager. For Presentation Manager applications, the User 
Interface Shell menus remain visible until explicitly removed by the user. 
For non-Presentation Manager applications, the User Interface Shell disap- 
pears when the application is on the screen. 

Non-Presentation Manager applications are not able to take advantage of 
the features of Presentation Manager. The section, “Running MS OS/2 
Kernel Applications Under Presentation Manager”, defines a non- 
Presentation Manager application. 

Presentation Manager applications are able to take full advantage of the 
features of the Presentation Manager functions. These applications do not 
have to use the Presentation Manager unique programming interfaces but 
do have to obey rules concerning their use of the display screen and the 
input devices. Put simply, when using the display and input devices an 
application must use the Presentation Manager programming interfaces 
and/or use the basic MS OS/2 VIO.., IvBD.. or MOU.. function calls. 

When the user wants to interact with a non-Presentation Manager appli- 
cation, the application always appears on the screen by itself. Non- 
Presentation Manager applications cannot share the screen with other 
applications. Neither can they share the screen with the User Interface 
Shell. Thus the application cannot be seen at all when the user is interact- 
ing with another application or the User Interface Shell. 

The User Interface Shell and all the Presentation Manager applications 
occupy the Presentation Manager Screen Group. They can all potentially 
appear on the screen simultaneously, in overlapped Windows. A Window 
is a rectangular region on the screen within which application data is 
displayed. The Presentation Manager screen has a ’Messy Desk’ 
appearence in that the rectangular windows can overlap one another. 
Where the windows overlap, only part of one window is displayed and the 
appearence is like that of papers on a desktop - ie. one piece of paper over- 
lays another and only the topmost one can be seen where they overlap. 

A simple example of the Presentation Manager Screen Group appearence is 
shown in the following diagram. 
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Figure 1.1 Typical Presentation Manager Screen Layout 



A Presentation Manager application generally has one window and can 
have many more. Windows are organised on a hierarchical parent-child 
basis. A child window always lies on top of and is contained within its 
parent window. The windows at the top of the structure (which can be 
thought of as children of the physical screen) are called top-level windows. 
An application may have one or more top-level windows. 

The top-level window with which the user is interacting is called the active 
window. This will lie visually on top of all other top-level windows. Key- 
board input is always directed to the input focus window. The input focus 
window is either the active window or a child of the active window. 

The mouse input is generally directed to the window that lies underneath 
the mouse pointer. 

Some user input is received by the User Interface Shell rather than an 
application. This input generally performs operations beyond the scope of 
a single application, such as allowing the user to switch the active window. 
Certain keys on the keyboard and the mouse cause this kind of input. A 
detailed description is provided in the section dealing with the User Inter- 
face Shell. 
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1.1. 2.3 The Pointer 

Part of the screen appearence related to input is the Pointer. The pointer 
is a small image which moves around the screen as the mouse is moved. It 
is displayed only on those systems which have a mouse attached. It 
appears on top of anything else displayed on the screen. 

Its appearence can vary. There is a System Pointer appearence, an arrow, 
which the pointer has by default. The shape can change when the pointer 
enters an application window. The pointer shape can also vary as it moves 
from selectable to non-selectable items on the screen. 

The position of the Pointer on the screen is termed the Action Point. The 
Pointer can be used to select objects by positioning the pointer over the 
object and pressing and releasing one of the mouse buttons. Since the 
pointer is generally a large object, the action point occupies a point within 
the pointer shape. This point must be chosen carefully to avoid confusing 
the user. For instance, the action point of the System Pointer is at the tip 
of the arrow. 



1. 1.2.4 Presentation Manager Windows. 

Presentation Manager windows are more than just simple rectangles on 
the screen. They have a number of optional features which occupy their 
borders, termed the frame window. The frame window gives the end-user 
access to a number of Presentation Manager functions. The frame window 
includes: 

• Borders 

• Caption 

• Scroll Bar 

• Menu Bar 

• System icon 

• Maximize and minimize icons 

The area in the centre of the window that would normally contain the 
main information content of the window is called the Client area. 
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S is the system icon 

M is the maximize icon 

N is the minimize icon 

0 is the thumb mark in the scroll bars 

Figure 1.2 Presentation Manager window with frame 



Window Border 

Presentation Manager windows have a border in one of four 
formats: 

• Normal border (that is not selectable by the user) 

• Heavy border (that is selectable by the user for opera- 
tions such as sizing a window) 

• A thin border (that is not selectable) 

• No border 

Caption 

The caption is the window name that appears at the top of a 
window. Highlighting of the caption bar indicates the win- 
dow with which the user is currently interacting. 

Scroll Bars 

A window can contain one or two optional Scroll Bars. 

There is a Vertical Scroll Bar which appears at the right of 
the window and a Horizontal Scroll Bar which appears at the 
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bottom of the window. The scroll bars can be used to move 
the data appearing in the window up and down or right and 
left, under either application or Presentation Manager con- 
trol. 



Menu Bar 



A menu bar is a horizontally aligned menu at the top of the 
window. The end user may make selections on the menu bar 
that either send commands directly to the application, or 
cause the selection of a pull-down menu. 

System icon 

The sytem icon is an icon that the user may select in order to 
activate the system menu for the window. The system menu 
contains functions such as move, size, ... 

Maximize icon 

The maximize icon is an icon that the user may select in 
order to change a window to its maximum size. 

Minimize icon 

The minimize icon is an icon that the user may select in 
order to change a window to its minimum size. 



1.1. 2. 5 Presentation Manager User Controls 

The Presentation Manager User Controls provide the application program 
with consistent means of interacting with the user to perform various 
standard operations. These are: 

• Interaction by use of menus 

• Interaction by use of dialog boxes 



1.1. 2. 5.1 Use of menus 

The use of menus to interact with an application will always commence 
with a menu bar. The menu bar is a horizontal bar along the top of a win- 
dow that contains a number of items. The items may be selected, one at a 
time, by the user. The selection of an item in the menu bar by the user 
will cause the appearance of a secondary menu, called a pull-down menu. 
The pull-down menu contains additional options, one or more of which 
may be selected by the user. On completion of the selection, the pull-down 
menu is removed and the application performs the required action. 
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Figure 1.3 Menu bar with pull-down menu 



1.1. 2. 5. 2 Use of dialog boxes 



1. 1.2.6 Presentation Manager Programming Functions 

Presentation Manager has a large Application Programming Interface 
which is subdivided into major functional groups: 

• Windowing - creation and control of windows within an application 

• Input and Message Handling 

• User Controls 

• Alphanumerics Output 

• Graphics Output 

• Bitmaps 

• A programmed interface to the User Interface Shell. 

It is not necessary for an application to use any of the Presentation 
Manager API functions in order to run as part of the Presentation 
Manager Screen Group and be windowed onto the screen with other appli- 
cations. An application using the VIO.., KBD.. and MOU.. functions of 
basic MS OS/2 can be windowed when Presentation Manager is present. 

No changes to the application are necessary. 

However, an application using the Presentation Manager API has access to 
a range of powerful functions which can enhance the functionality and 
usability of the application while at the same time reducing the effort 
required to produce it. 
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A summary of the groups of functions in the Presentation Manager API 
follows. A thorough description of the functions and their uses is given in 
later sections. 



Windows 

An application can create and use a number of windows on 
the screen via the Windows API. Function is provided to 
control the size and position of a window and also to control 
whether the user can size or position a window. The applica- 
tion can specify the form of the window frame. The applica- 
tion can also control the data which appear in each window 
and can control which window is the Input Window. 

User Interface Controls 

The User Interface Controls API provides the application 
with functions for dialog between application and the user. 
The functions include: 

• The display and interaction with menus. 

The following menus are supported: 

• Menu Bars 

• Pull-down menus 

• Control functions that an application would typically 
group together into a ’dialog box’. These are: 

• Scroll bars 

• Buttons 

• Edit controls 

• Static controls 

• List boxes 

• Message boxes 
Input and Message Handling 

The Input API allows the application to control the input it 
receives, both from the user via the Mouse and Keyboard 
and from the system and other applications in the form of 
messages. The input is based on an application input queue, 
and one or more Window processing functions. 

Alphanumerics Output 

The Alphanumerics output API, termed Advanced Vio, is 
used to output simple Alphanumeric data into screen Win- 
dows or into Bitmaps. Advanced Vio is an extension of the 
basic MS OS/2 VIO.. functions for a windowing 
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environment. Advanced Vio also allows use of multiple fonts 
and features such as underscoring of individual characters. 

Graphics Output 

The Graphics API, called the GPI, is used to draw graphics 
data into screen windows, bitmaps, or other devices such as 
printers and plotters. The application can draw a range of 
graphics objects, such as Lines, Arcs, Text Strings, Closed 
Areas and Images. Various attributes of the primitives such 
as their Colour, Area Fill pattern, Character Font and Line 
Style can be controlled. The size, orientation and position of 
every primitive can be varied by means of Transformations. 

The GPI also supports a wide range of text functions, includ- 
ing the support of fonts. 

Graphics data may be managed by the application or stored 
and managed by the Presentation Manager system. 

Bitmaps 

The Bitmap API allows creation and use of Bitmaps. Bit- 
maps are best thought of as images similar in form to the 
screen image. Bitmaps can be drawn into in a similar 
fashion to the screen; they may reside either in PC memory 
or in memory associated with a particular device. Bitmaps 
can also be the source of data to place on the screen. They 
can be used to produce rapid changes to the screen, such as 
changing a Menu, in cases where normal drawing would be 
too slow. 

User Interface Shell API 

Presentation Manager contains an API that will allow appli- 
cations to request some of the shell functions normally 
requested by the user. 
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2.1 How to Write a Windows 

Presentation Manager Application 



This section describes how to write a Windows Presentation Manager 
application. It describes the environment in which a Presentation 
Manager application runs and gives a guide to the concepts and methods 
of using the Presentation Manager API. A detailed description of the 
Presentation Manager API is in the later sections. 

2.1.1 The Purpose of the Presentation Manager API 

The basic purpose of the Windows Presentation Manager is to provide 
easy accessibility for the user to the functions provided by the PC system. 
It does this in conjunction with the MS OS/2 kernel and together they 
help the user accomplish whatever tasks need doing, as and when they are 
needed. 

An important feature of MS OS/2 is that of multi-tasking. The system 
can perform a number of tasks simultaneously - multiple application pro- 
grams can run at the same time. Presentation Manager allows the user to 
see the data belonging to many applications simultaneously, so that one 
set of data can be used in conjunction with another. 

Presentation Manager makes it easy to get things done. In contrast to the 
situation on MS-DOS, there is no need to stop one application program 
just because the user needs to run another to get access to some piece of 
information. Presentation Manager provides means to start any task at 
any time. It provides means to view many tasks simultaneously on the 
screen. Presentation Manager also provides means for copying data from 
one task to another ("Cut and Paste") which really makes the use of mul- 
tiple tasks interesting and useful. 

For application programs, Presentation Manager provides shared access to 
the general resources of the PC system, which include: 

• The Screen 

• The Keyboard 

• The Mouse 

• Printer(s) 

• Plotter(s) 

• Picture Files 

• Other Applications 

Presentation Manager makes the access to the resources simple. 
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Presentation Manager also simplifies the process of writing an application 
through the functions provided in the API and the various utility pro- 
grams provided in the Toolkit. 

The Presentation Manager API does require applications to behave in cer- 
tain ways, in order to share resources effectively. In simple terms, applica- 
tions wishing to take advantage of the Presentation Manager features 
must behave in a Co-operative fashion. Applications must co-operate with 
both the Presentation Manager system and other applications in order 
that the system works to the benefit of the end-user. 

The Presentation Manager API is structured around these basic ideas and 
does make some demands on the way applications work. This is made 
clear in later sections. 

MS OS/2 applications that do not wish to take advantage of the Presenta- 
tion Manager facilities can run in a PC system that is using Presentation 
Manager. How such applications run in a system using Presentation 
Manager is dealt with in a later section. 
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2. 1.1.1 Presentation Manager Basic System Structure. 
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Figure 2.1 Presentation Manager - System Structure. 



2.1. 1.1.1 The User Interface Shell 

In the user’s eyes, the major part of the Presentation Manager system is 
the User Interface Shell. The User Interface Shell presents the user with a 
view of the various components of the system. It allows the user to: 

• get tasks (applications) running 

• work with a particular application 

• control the layout of applications on the screen, including position 
and visibility 

• view and work with the data files in the system 

• control the Printer(s) and Plotter(s) attached to the system 

• control various aspects of the appearance and operation of the sys- 
tem, such as the screen colors 
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The User Interface Shell is designed to make the system easy to under- 
stand and easy to use. It gives rapid access to the capabilities of the sys- 
tem. At the same time, it is functionally very rich and caters for the 
expert user. Applications should be written with the functions of the User 
Interface Shell in mind - to avoid unnecessary duplication. 

It is important that the various parts of the User Interface Shell and the 
application programs in the system have the same Style. This means that 
they are uniform in appearance and all work in the same kind of way, even 
though the function provided by different applications may be very 
different. This means that the user does not have to jump from one 
environment to another and can proceed with ease from one task to the 
next. In fact, the user should not really be aware of moving from one 
application to another. 

The Presentation Manager API makes it easy for a program to conform to 
a standard Style. This is discussed in detail in a later section. 

Thus, the User Interface Shell provides access to the system, to various 
utilities and to the applications installed in the system. 



2.1. 1.1.2 The API 

Applications access the functions of the Presentation Manager system via 
the API. The API and its associated Utilities simplify the process of writ- 
ing an application. It provides the following broad areas of function: 

• Display of Data on the Screen and on Printers and Plotters. The 
data may be simple Text (’Alphanumerics’) or Graphics (including 
high quality Text). 

• Presentation and Operation of Standard User Menus and Dialogs 
on the screen to aid the user in accomplishment of some task. 

• Interaction with other Functions or Applications in the system, 
including Shell processes and functions. 

• User Interaction and Input functions. 

• Partitiioning of Screen data, economical use of Screen area and 
structuring of application functions. 

The description of the API is divided into a number of functional areas: 



Shell access to aspects of the User Interface and to the Utilities 
that form part of the User Interface Shell, including: 

• Starting of Programs - Program Names 
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• Listing of running applications 

• Clipboard - copying of data between programs 

• Program environment information - initial values for 
position and size of an application, for example. 

Windows 

involves provision of areas on the screen in which to draw 
data. However, the function is much more extensive than 
this, and touches on: 

• program structuring including object-oriented program- 
ming 

• user interface functions 

• user input 

• inter-program communication. 

Input which covers: 

• user input from Mouse and Keyboard 

• system messages and inter-application messages 

• timer functions 

Dialogs and Menus 

which includes: 

• Display and operation of Menus offering the user 
straightforward selections from a list of items. 

• Creation, display and operation of Dialogs which offer 
the user more complex forms of interaction with the 
application 

Alphanumerics Output 

which is the output of simple textual information to the 
screen, printers, plotters and files. This offers a way of 
displaying text in a simple form as fast as possible. 

Graphics Output 

which allows the application to create and display graphical 
data on the screen, printers, plotters and files. This includes 
high quality and high function typographical text functions. 

Bitmaps 

which allow the creation of bitmapped graphical images for 
the purpose of rapid manipulation of the appearance of the 
screen. 
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2.1.2 API - General Features 

The Presentation Manager API provides functions for the Interface 
between an application program and the user sitting in front of a PC. For 
most applications, this means: 

• Output Functions for the presentation of data of various forms on 
the Screen in a consistent manner. 

• Input Functions for the handling of user requests and responses. 

Devices other than the screen are also supported for data output, such as 
Printers, Plotters and Data Files. However, these devices do not partici- 
pate directly in the interface between the application and the user. 

Presentation Manager organizes its user related functions, both output 
and input, around Screen Windows. An application can create as many 
windows as it desires. Each window serves a part in the dialog between 
application and user. One window at a time is the center of attention for 
the user, although other windows may be visible and convey useful and 
important information. 

The way in which an application uses the Presentation Manager API is 
summarized in. 
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Figure 2.2 Application Model for Input and Output. 



2. 1.2.1 Output Fundamentals 



2. 1.2. 1.1 Output Data 

The application creates output data in one of three forms: 



Alphanumeric Data 

which is Text and Numeric data displayed on a fixed grid of 
character ’slots’. These are held in an Alphanumeric Presen- 
tation Space. 
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Graphics Data 

such as lines, circles and shapes filled with colored patterns. 
These are held in a Graphics Presentation Space. 

Dialog Data 

which includes items which the user can Select or Type into 
as part of a structured dialog between application and user. 
This is held in a Menu or Dialog Box. This data is only 
displayed on the screen and not on other devices such as 
printers since it relates directly to the user interface. 

Each type of output data has its own set of functions for creating and 
modifying the data. The data is essentially independent of the place 
where it is eventually drawn - it is a logical representation of what is 
required. Thus, for example, a picture can be created in a Graphics 
Presentation Space, first drawn onto the screen and then drawn onto 
paper by a printer. 

An application may have many instances of each type of data, depending 
upon the application’s requirements. For example, an application would 
have many Menus and Dialog Boxes if it needed a lot of structured input 
from the user. 



2. 1.2. 1.2 Devices 

Output data is drawn onto a Device. For Dialog Data, the device is always 
the Screen. For Graphics and Alphanumerics data the application must 
Associate the Presentation Space with a Device. In these cases, the Device 
may be the Screen, a memory Bitmap, a Printer, a Plotter or a File. The 
association can be changed by the application so that the same data can 
be directed to a number of places in sequence, typically following user 
requests. 

A device is logically represented by a Device Context, which encompasses 
the Device Driver required to use the device, and State Data which includes 
appropriate physical realizations of device dependent objects such as Text 
Fonts. 



2. 1.2. 1.3 Screen Windows 

Output data is drawn onto the Screen through one or more Windows. 

Each separate Presentation Space or Dialog Box is normally shown in its 
own window. The windows are created by the application. Windows are 
rectangular in shape and are fitted onto the screen in a ’Messy Desk’ 
arrangement. This means that the windows are treated like a series of rec- 
tangular pieces of paper on a desk. The windows can overlap one another. 
Where they overlap, only one of the windows can be seen - the windows 
have an ordering where one window lies ’on top’ of another. Where they 
overlap, the ’topmost’ is seen. 
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The screen displays all the currently visible windows of all the applications 
that are running in the Presentation Manager screen group. An applica- 
tion can control the ordering of its own windows relative to one another. 

It does not control the ordering of its windows relative to the windows of 
other applications. This is done by the Presentation Manager system 
according to user requests. 

Windows are not used on devices other than the screen. This is because 
their main use is in enhancing the end-user interface. The screen is special 
- it is used in a highly interactive way and space for the display of impor- 
tant information is limited. Multiple applications can use other output 
devices serially, but in a highly interactive environment it is important for 
the user to be able to see and use multiple applications simultaneously. 
Similarly, objects such as Menus and Dialogs are used for short periods at 
a time and should not occupy screen space except when needed. Thus they 
are placed in windows which can be made invisible. 

As well as being a place where an application can display data on the 
screen, windows have a User Interface aspect as well. The user can alter 
the position and/or the size of some (but not all) windows. This allows 
the user to layout work on the screen in a convenient way. To achieve this 
function, windows have a variety of Controls which occupy their borders 
and allow the user to manipulate the window in a number of ways. 



2. 1.2.2 Input Fundamentals 



2. 1.2. 2.1 User Input 

The end user of the system creates input using the Mouse and Keyboard 
devices. The user can create the follwing Input Events: 

• Mouse Button up/down 

• Mouse Movement 

• Keyboard Key up/down 

Each input event is called a Message. User input is asynchronous to appli- 
cations - that is, the user can press keys or move the mouse to create input 
independently of the speed with which an application can process the 
input. All the user’s input is buffered as a sequence of Messages in an 
Input Queue before reaching the application. This ensures that input is 
not lost and is correctly sequenced. The application reads the input mes- 
sages from the queue one at a time using the Get Message or Peek Message 
functions. 
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There is a close relationship between user input and windows. The user 
directs input to one window at a time. Each input event is tagged with 
the ID of the window to which it is directed. Every window is associated 
with one input queue. Thus input related to a particular window can only 
be received by reading a particular queue. A single queue can receive 
input for any number of windows, however. 



2. 1.2.2. 2 Other Kinds of Input 

Input other than Mouse and Keyboard messages can also appear on an 
input queue. This includes: 

• Timer messages, which occur after an application-set Timer expires 

• System messages, which inform the application of various system 
related events. A typical system message is the Paint message, 
which informs the application that a window (or part of a window) 
needs to be repainted/redrawn. This often occurs when some or all 
of the window becomes visible as a result of the user performing a 
windowing operation. 

• Inter- application messages, which are sent from one application to 
another. These typically occur between applications which are 
cooperating in some way. Such messages have application-defined 
meaning. 

2.1.3 Presentation Space, 

Device Contexts and windows 

2. 1.3.1 Presentation spaces 

A presentation space contains the device-independent quantities required 
to perform output to an individual window or device. These include:- 

• A definition of the picture data itself. 

For VIO output, this is the VIO buffer. For a graphics picture, this 
could be a graphics segment store (though if non-stored processing 
is being used, segments are not kept by the system). 

• Clipping region as defined by the application. 

• Definition of any fonts required for drawing. 

This is essentially a logical description of the fonts, and does not 
include any physical font definitions. 

• Co-ordinate mapping. 

An indication of how world co-ordinates are to be mapped to the 
device. 
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• A definition of the colors an application would like. 

• The default attributes associated with the picture. 

A presentation space is always required whenever the application wishes to 
use any of the GPI or Advanced Vio functions to output data on an output 
device or into a bitmap. All of the GPI and Advanced Vio calls require the 
presentation space handle to be specified as a parameter. The presentation 
space is created by the VioCreatePS or GpiCreatePS functions. 

Before a presentation space can be used to draw a picture, it must be asso- 
ciated with a Device Context. (Refer to following section on Device Con- 
texts.) After this has been done, any drawing operations issued to the 
presentation space cause output to occur on the device defined by the Dev- 
ice Context. 

The presentation space can subsequently be associated with a different 
Device Context, and the picture redrawn on that device. Because all of 
the ’application intent’ information is kept in the presentation space, the 
system is able to draw the picture as faithfully as possible on this second 
device. 

Thus a picture which is currently visible on the screen can be printed by 
temporarily re-associating its presentation space with a Device Context 
whose device is a printer, and re-drawing the presentation space. In order 
to continue drawing on the screen, the presentation space is now re- 
associated back to the screen Device Context. 

(Note that the above scenario is only as simple if the entire picture 
definition has been stored in the presentation space. If non-stored graph- 
ics have been used, then the application needs to redraw the picture again 
after associating with the printer Device Context. However, it still does 
not need to respecify any of the logical objects, for example fonts, which it 
needs, since these are still kept in the presentation space.) 



2. 1.3. 2 Device Contexts 



A Device Context is the means of drawing to a particular device. It 
includes a device driver, and also physical realizations, where appropriate, 
of device-dependent objects which the drawing process requires. 



There are four kinds of Device Context, as follows:- 

• Screen Device Context. This causes drawing to be performed to a 
particular window on the screen. 

• Memory Device Context. This is used only for drawing to a 
memory bitmap. 
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• Metafile Device Context. This causes the picture to be transmitted 
to a metafile, which may be used to store a picture in editable 
form. 

• Queued device Device Context. This is used for some device other 
than the screen, for example, an attached printer or plotter, where 
the output is to go via the spooler. 

• Directly attached device Device Context. This is used for some 
device other than the screen, for example, an attached printer or 
plotter, where the output is not to go via the spooler. 

• Information Device Context. This is used for some device other 
than the screen, for example, an attached printer or plotter, but 
where no output will occur. Its purpose is to satisfy queries. 

A Device Context is required whenever the application wishes to use any of 
the GPI or Advanced Vio output functions. However, the Device Context 
is not normally specified on the GPI or Advanced Vio calls; instead a Dev- 
ice Context is associated with a particular presentation space, by the 
application issuing a GpiAssociate or a VioAssociate call (an implicit asso- 
ciation is also possible in the Gpi case). The Device Context must be 
specifically created by the application in all cases. The application uses 
the DevOpenDc call to create a Device Context for a printer, bitmap, or 
metafile. In the case of the display screen, the Device Context for a win- 
dow is created by a call to WinCreateWindowDC after the application 
creates the window with a WinCreateWindow call. 



2. 1.3. 3 Windows 

A Presentation Manager window is a rectangular area on the screen. A 
window contains visual data displayed from a Presentation Space, for 
example a Graphics (GPI) Presentation Space, which is associated with the 
window. Alternatively, a window could display data from a dialog box. 

The screen can have many windows displayed and these may overlap. 
Where overlap occurs, the windows have a priority ordering. At any point 
on the screen, the window with the highest priority gets displayed. 

Presentation Manager windows are of two types: 



Main Windows 

A Main window has the property of being positioned relative 
to the screen itself. It is not related to any other window. 
Operations on one main window do not affect other main 
windows. 

An application can have as many Main windows as it wants, 
within overall implementation limits. 
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A main window may be considered to be a child window of 
the entire screen. 

Child Windows 

A Child window has the property of being positioned relative 
to another window, termed its Parent. The Parent window 
can have multiple Children. Operations on the Parent win- 
dow affect the Child. For example, moving the Parent moves 
the Child and hiding the Parent hides the Child. 

A Child is constrained to fit within the client area of its 
Parent A Child window always has a higher priority than its 
Parent, i.e. it cannot be hidden simply by virtue of being 
underneath its parent. A Child window may have Children 
of its own. 

An application can have as many Child windows as it wants, 
within overall implementation limits. 



2.1.4 Presentation Manager functions 

2. 1.4.1 Output via GPI or Advanced Vio functions 

The data displayed in each window is held in a Presentation Space which 
is created and manipulated by the application separately from the win- 
dow. The Presentation Space is different for different types of data - a 
GPI presentation space for Graphics/Image data, and an Advanced Vio 
presentation space for alphanumeric data. 

The application output does not go directly from the presentation space to 
the screen window. It goes through a ’Device Context’. The Device Con- 
text encapsulates various physical characteristics of the output device. 

The main utility of the Device Context is for the support of other devices 
such as printers or memory bitmaps. 
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Figure 2.3 Presentation Manager application model for graphics and alphanumerics 



Thus to display some data on the screen, the application: 

1. creates a Window (this will implicitly create a Device Context that 
is associated with the window) 

2. creates a Presentation Space 

3. associates the Presentation Space with the Device Context, so that 
data drawn from the Presentation Space goes into the Window 

4. creates the data to display by operating on the Presentation Space 

5. puts the data into the Window by means of a draw operation on 
the Presentation Space 

Note that for Gpi, items 2 and 3 can be combined in a single call, and also 
in non-stored mode items 4 and 5 are combined. 



2. 1.4. 2 Output via User Controls functions 

When an application wishes to use the User Controls functions, it does not 
specifically create a presentation space. Instead, it interacts directly with a 
dialog box or menu object. These objects incorporate the concepts of win- 
dow, presentation space, and Device Context. 

In addition, the input that the application receives from the User Controls 
is processed by Presentation Manager and returned to the application in 
terms of the particular dialog box or menu. 
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Figure 2.4 Presentation Manager application model for dialog boxes 



2. 1.4. 3 Input Functions 

In Presentation Manager, input to an application is a sequence of Messages 
generated by any of a number of sources. The Messages are placed on an 
application Input Queue in time order and are read from the queue by the 
application. All Presentation Manager applications have at least one 
input queue - the Default Input Queue. In addition, the application may 
create additional input queues. Every window created by the application 
will have a single input queue associated with it. Most input messages are 
associated with one of the application’s windows, and are sent to the 
appropriate queue. 

In addition to an input queue, every window normally has a window pro- 
cessing function associated with it. It is the job of the window processing 
function to process the input associated with a window. The main pro- 
gram of the application will read the input from the input queue by use of 
the GetMessage function, and then route the input to the appropriate win- 
dow processing function by means of the DispatchMessage function. 

It is the responsibility of the application to be ’well-behaved’. This means 
that an application must always issue a GetMessage to read its input 
^ueue within a short time period (e.g. O.lsec) of receiving the previous 
input. In order to achieve this, it must have dispatched the window pro- 
cessing function, and the window processing function must have completed 
and returned within the specified time. 
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If the application does not meet these requirements, various system func- 
tions and/or other applications will be locked out until the application 
completes processing and reissues its read on the input queue. 

2.1.5 Sample Programs 

A number of Sample Programs are supplied with Presentation Manager to 
help programmers understand the Presentation Manager API and give 
hints as to how the API can be used to achieve results. Each sample pro- 
gram tackles its own functional area: 

• Use of Windows. 

• Use of Menus and Dialogs. 

• Advanced Vio alphanumerics for display of Text. 

• Keyboard and mouse input. 

• Graphics: 

• Direct (non-stored) drawing of pictures 

• Stored creation, drawing and editing of pictures 

• Correlation 

• Dragging 

• Bitmap operations 

• Printing 

• Typographic fonts 

• Use of the clipboard. 

2.1.6 Application Model 

This section covers various aspects of writing an application to use the 
Presentation Manager facilities. Presentation Manager places a number of 
requirements on the way an application is structured and the way in which 
it uses certain facilities, especially Input and the Screen. 

Note that special considerations apply to MS OS/2 applications which use 
multiprogramming methods, ie. multiple processes or multiple execution 
threads. These considerations are dealt with in the chapter, “Multipro- 
cessing and Inter-Process Communication” 
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2. 1.6.1 Basic Application structure. 

To use the Presentation Manager API, a program must call the Winlnitial- 
ize function before any other Presentation Manager function. This func- 
tion identifies the application to Presentation Manager and initializes the 
application’s environment. 

The Winlnitialize function returns an Anchor Block Handle which has the 
purpose of holding the application’s Presentation Manager environment 
data. The Anchor Block Handle must be stored by the application for 
later use - it is required by a number of Presentation Manager functions, 
such as WinCreateWindow. 

Once Winlnitialize has been called, the application can use any other 
Presentation Manager function - to display data on the screen or receive 
input from the user, for example. If another Presentation Manager func- 
tion is called before Winlnitialize, it fails and returns an error code. 

When the application is about to finish, it should call the WinTerminate 
function. This is the inverse function to Winlnitialize - it destroys the 
application’s Presentation Manager environment. After WinTerminate 
has been called, the application cannot make any further Presentation 
Manager function calls. If the application makes any Presentation 
Manager function calls after WinTerminate has been called, the function 
fails and an error code is returned. 

WinTerminate deallocates and destroys any Presentation Manager 
resources that were allocated to the application, such as Windows and 
Presentation Spaces. However, it is recommended that such resources are 
explicitly destroyed by the application before calling WinTerminate - this 
allows the application to perform a tidier ’cleaning up’ of the resources, 
including saving data in disk files if required. 



31 




Windows Presentation Manager Reference 



Program Fred; 

k k k k 
k k k k 
k k k k 



I 

I 

I 



>- 



I 

- + 



Program 



Initialization 



Winlnitialize ( 



Presentation Manager Initialization 



k k k k 
k k k k 
k k k k 




Main body of the program. 



WinTerminate ( ) ; 



k k k k 
k k k k 
k k k k 



End Program Fred; 



Presentation Manager Termination 




Program Termination 



Figure 2.5 Application Structure. 



2. 1.6. 1.1 Normal and Abnormal Application Completion. 

An application which uses the Presentation Manager API normally allo- 
cates various resources to itself, such as Windows, Presentation Spaces 
and Input Queues. It is recommended that the application deallocates and 
destroys all these resources before it finishes. 

If the application fails to deallocate any Presentation Manager resources 
before finishing, for example by failing to call WinTerminate, then these 
resources are still deallocated by the system. This occurs, in DOS terms, 
when the Exit List processing occurs. Note: This applies whether the 
application finishes normally or abnormally (due to some error). The 
Presentation Manager system ensures that no resources are left ’lying 
about’ once the application finishes. 

It is better if the application explicitly destroys any resources since the 
application can do things in a more coherent order - especially from the 
appearance of things on the screen. The application can also save away 
any data associated with the resources, if necessary. 
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2. 1.6. 2 The System Environment - The Shell and Other Applica- 
tions. 

In Presentation Manager, an application does not stand on its own. It is 
part of a system which interfaces to the user. In particular, the User Inter- 
face Shell forms a major part of the interface and it is through the User 
Interface Shell that the application is started and is accessed when run- 
ning. 



2. 1.6. 2.1 Starting an Application 

When the user starts an application, this is done via some selection(s) from 
windows in the User Interface Shell. The application is represented there 
by a Long Name, which is more meaningful to the user than an eight letter 
filename. 

Once an application is running and it creates and displays a main window, 
the window must be given a Title, so that the user can identify the appli- 
cation. 

The User Interface Shell also has a Switch List containing the names of all 
the main windows of applications in the system. This allows the user to 
find an application of interest when the system is running more than one 
application on the screen and some of the applications are obscured by 
other applications’ windows. It is the application’s responsibility to put its 
entry into the Switch List. 

The Long Name by which an application is started can be found by calling 
the WSHGetStartupName function, which is part of the Shel API. It is 
recommended that an application uses this name for its main window and 
for its entry in the Switch List. However, where the application is working 
with a particular data file, it is also recommende d that the file name is 
appended to the Long Name to form the Window Title and the Switch List 
entry. 



2. 1.6. 2. 2 Main Window Title 

The title of the application’s main window is set in the Win- 
CreateFrameWindow function when the window is created. However, the 
title can be updated subsequently by sending a 

WM— SETWINDOWP ARAMS message to the window, for example if the 
application starts work on another file. 
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2. 1.6. 2. S Switch List Entry Name 

The Switch List entry is created by the WSHAddSwitchEntry function. 

The Name displayed in the Switch List is specified as a parameter to this 
function, along with the Window Handle of the application’s main win- 
dow. When the user selects the Switch List entry belonging to the applica- 
tion, the main window is made Active and it is brought to the top of the 
stack of windows. 



2. 1.6. 3 Program Structure and Windows - Window Procedures. 

A Screen Window is not only used as a place to put display data. Win- 
dows have an important role in a number of aspects of the Presentation 
Manager API: 

• Display of multiple sets of data on the screen. 

• Efficient use of scarce screen area. 

• Handling of Input - both from the user and the system. 

• Program structuring and partitiioning. 

• A seamless way of extending System functions. 



2. 1.6. 4 Application Rules And Conventions 



2. 1.6. 4-1 Mouse Button Activation of a Window 

It is the application’s job to transfer active status to one of its windows if 
it gets a mouse down message. It should do this by calling WinSetFocusQ 
or WinSetActiveWindowQ with the window that the mouse message was 
sent to. 



2. 1.6. 4-2 Active Windows, Dialog Boxes and User Expectations 

The application should not call WinSetActiveWindowQ arbitrarily to set 
the active status to one of its windows. This should only be done as the 
result of an explicit user action requesting a new window to become the 
active one or as the result of a message from the shell to the same effect. 

Neither should an application display a dialog box or message box arbi- 
trarily if it needs to tell the user something and it doesn’t own the active 
window. Applications that need to do this should call MessageBeepQ a few 
times and then call Flash WindowQ. Flash WindowQ will start the frame of 
the window flashing. The user will hear a beep and see the window flash- 
ing. The user can then choose to pay some attention to the application, 
and request that it become the active one, say by clicking the mouse with 
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the pointer in the flashing window. The application can then call 
Flash Window() again to turn off the flashing, and bring up an appropriate 
Message or Dialog. 



2.1.6.4-8 Mouse Cursor Shape within a Window 

It is the application’s job to set the shape of the mouse cursor when it gets 
a WM_MOUSEMOVE message, using the SetCursorQ call. Child windows 
should send the WM_ CONTROLCURSOR message to their parents, so 
their parents can have the choice of setting their cursor shapes. See ’Con- 
trol Manager’. 



2. 1.6. 5 Building a Presentation Manager Application 

This section describes the method of building a Presentation Manager 
application. This includes details specific to Presentation Manager appli- 
cations that do not apply to other DOS applications. The reader is 
assumed proficient in building general DOS applications. 

The following describes the source files required for Presentation Manager, 
and the processes through which these are turned into an executable file. 
The application programmer is responsible for providing three types of 
source files: 

• a resource file 

• one or more source code files (i.e. C or assembler files) 

• a DOS module definition file. 



2. 1.6. 5.1 Resource Files 

The resource file contains descriptions of the application’s user interface 
data, such as dialog boxes or menus. The application programmer defines 
these either through a text description, or by using a tool such as the dia- 
log editor which will in turn create the text description. 

The Resource Compiler understands these descriptions, and performs two 
functions in building an application. First, it compiles the text description 
into a binary format suitable for the Presentation Manager system. 

Second, it inserts these binary resources into the executable file. The 
insertion must be done after linking the objects, i.e. the sequence is: 

link 

re 



35 




Windows Presentation Manager Reference 



The resource compiler is invoked through the command: 
rc resourcefilename [exe filename] 

The resourcefilename is the DOS filename of the resource text file. If no 
extension is specified, the extension is assumed to be RC. The exefilename 
is optional, and is the name of executable to insert the binary resources 
into. If it is not specified, then the default is the executable with the same 
filename as resourcefilename, i.e. 

rc sample 

rc sample. rc 

rc sample.rc sample.exe 

would all compile the resources described in sample.rc and would insert 
them in sample.exe. 

Compilation of the resources takes time, and the resources must be rein- 
serted in the executable every time the application is relinked. Thus, to 
save application build time, the Resource Compiler has an option to com- 
pile the resources and then create an intermediate object file. This 
resource object file can then in turn be specified as input to the Resource 
Compiler, to complete the final step of insertion into the executable. 

To create the intermediate object file, specify the "-r" option, which will 
create a file whose extension is RES. 

Example: 

rc -r sample.rc 
link 

rc sample. res sample.exe 



2. 1.6. 5.2 Source code 

High level language files are compiled using the appropriate language com- 
piler; assembler files must be assembled. In both cases, intermediate 
object files (.OBJ) should be created. 



2. 1.6. 5. 3 Module Definition File 

All external entry points in a Presentation Manager application must be 
EXPORTed in the Module Definition File (.DEF^. See "Building an OS/2 
Application" for a further description of the .DEF file. 
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2. 1.6. 5. 4 Linking A Presentation Manager Application 
At link time, the developer must specify: 

• the code object files to be linked (.OBJ’s) 

• the Module Definition File (.DEF) 

• Libraries (.LIB’s) 

In order to resolve references to Presentation Manager API, the developer 
must specify Wincalls.lib in addition to any other necessary libraries. 

Sample Build Sequence 

• rc -r sample => creates sample. res 

• Compile sample. c = creates sample. obj 

• Link sample. obj, sample.def, wincalls.lib => creates sample.exe 

• rc sample. res => modifies sample.exe 

Sample.exe is now ready to run under Presentation Manager. 

2.1.7 Background to user interface 

The MS OS/2 user interface is a set of rules intended to provide end users 
with a consistent, easy-to-use interface across applications. 

It includes many elements of user interaction with the system, such as 
menu selection and text string input, but it does not include iteractions 
specific to applications, such as spreadsheet editing. 

Where an application has user interaction in areas covered by user inter- 
face rules, it must conform to the user interface. 

The principal topics in the user interface are as follows: 

1. Key assignments 

2. Menu colors 

3. Application action bars 

4. Pop-down menus 

5. Scroll bars 

6. Types of selection fields 

7. Entry fields 
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8. Message and Help panels 

9. Window sizing and moving. 

Presentation Manager allows all applications to conform to the user inter- 
face. For some rules, Presentation Manager enforces conformance by tak- 
ing over complete parts of the operator interaction. Thus, for these 
interactions, the only way the application could avoid being in confor- 
mance would be to rewrite part of the code provided with Presentation 
Manager. 



2.1.8 Naming Conventions 

Here is a short description of the variable and argument naming conven- 
tions used in the Presentation Manager spec. A name is made up of a tag 
prefix and an opti onal identifier. The tag is all lower case, and the 
identifier begins with an upper case letter. You can either make up your 
own tags for new data types, or use some combination of the standard 
tags. 



2. 1.8.1 Constant names 



All constants are written in upper case. If applicable, constant names 
have a prefix derived from the name of a function, message, or idea associ- 
ated with the constant. For example: 



WM_CREATE 

WS_CLIPSIBLINGS 

DT_CENTER 



Window message (WM_*) 
Window style (WS_*) 
DrawText () code (DT_*) 



2. 1.8. 2 Type names 

Type names are written in upper case. Type names are usually longer and 
more descriptive than their variable and argument prefixes; for example: 

Type Prefix 

RECT rc 

POINT pt 



2. 1.8. 3 Variable and argument names 

A name is made up of a tag prefix and an optional identifier. The tag is all 
lower case, and the identifier begins with an upper case letter. You can 
either make up your own tags for new data types, or use some combination 
of the standard tags. 



38 




Application Model 



Standard name 

P 

lp 

d 

c 

i 

rg 

f 

h 

ch 

b 

w 

1 

id 

it 

cmd 

pfn 

lpfn 

psz 

lpsz 

rgf 

lrgf 

brgf 

Standard type 

hab 

hwnd 

rc 

pt 

hmenu 

t 

x 

Y 

hps 

hvps 

hdc 

hbm 

hrgn 

hcsr 

hdc 

msg 

style 

Standard type 



prefixes : 

near pointer 

far pointer 

delta 

count 

index 

array 

boolean 

handle 

character 

byte 

word 

long 

ID 

item 

command 

near function address 
far function address 

near ptr to zero termintated string 
far ptr to zero terminated string 

16-bit packed array of flags/bits 
32 -bit packed array of flags/bits 
8-bit packed array of flags/bits 

abbreviations : 

Anchor block handle 

window handle 

rectangle 

point 

menu handle 

32-bit millisecond value 
x coordinate 
y coordinate 

PS handle 

VIO PS handle 

device context handle 
bitmap' handle 
region handle 
cursor handle 
DC handle 

window message ID 
32 -bit window style 

identifiers 
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Next - Next 

Prev - Previous 

First - First value (used with Last) 

Last - Last value (== last value, not one greater) 
Min - Minimum value (used with Max) 

Max - Maximum value (one past last possible) 

Examples : 



pch 

rgbBuf fer 
dx 

cyMax 

rgfMenu 

lpphwnd 



- Near pointer to a character (or characters) 

- Array of bytes 

- Delta-x value 

- Max count of y coordinates 

- Menu command values 

- Far pointer to a near pointer to a window handle. 



2. 1.8. 4 Assembly language structure fields 

In assembly language, all structure field names must be unique. Since not 
all structure fields have unique names, the assembly language convention 
is that all field names are prepended with the structure type abbreviation 
and an underscore. Here are some examples: 

RECT xLeft field: rc_xLeft 

POINT y field: pt_y 



2. 1.8. 5 Standard Data Types Used in this Document 

Below is a list of the standard data types used in this document: 



Type Description 

CHAR Signed 8-bit value or character 

INT Signed 16-bit value 

LONG Signed 32-bit value’ 

UCHAR 

Unsigned 8-bit value 
UINT Unsigned 16-bit value 
ULONG 

Unsigned 32-bit value 
LPSTR Far pointer to a character string 
BOOL 16-bit Boolean (zero => FALSE, non-zero => TRUE) 
HANDLE 

32-bit handle 
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SHANDLE 

16-bit handle 

FARPROC 

Far pointer to a procedure 

Here are the standard declarations in C for these types: 

typedef unsigned char UCHAR; 

typedef unsigned int UINT; 

typedef unsigned long ULONG; 

typedef char FAR *LPSTR; 

typede f int BOOL ; 

typedef long LONG; 

typedef char FAR *HANDLE; 

typedef unsigned int SHANDLE; 

typedef int (FAR * FARPROC) () ; 

2.1.9 Return Code Conventions 

This section documents the strategy for return codes used for Presentation 
Manager. 

Each function is allocated to one of the following types, depending upon 
the ranges of the values which it returns:- 

• Restricted range return values 

Where these are successful, a value within a specified range is 
returned. If there is an error, a value outside the valid range (or a 
special value within the range) is returned. The error code may be 
obtained by WinGetLastError. 

Functions which return handles are a form of this type (0 and -1 
are assumed to be outside the range of valid handles). 

Examples: WinCreateWindow, GpiQueryMix 

• Defaulted return values 

Functions for which a documented, reasonable default behavior 
exists if an error occurs. Errors in these situations are not interest- 
ing, and not harmful to applications. 



41 




Windows Presentation Manager Reference 



Example: WinlsWindowVisible () 

• Failsafe unrestricted range return values 

These functions tend to be speed critical, and the return value will 
be returned in AX. 

Example: WinGetCurrentTime 

• No return values, or structure return values, or unrestricted range 
return values: 

Error code (Boolean) is returned in AX; the return value(s) (if any) 
are returned through parameter(s). 

Example: GpiQueryAttrs 

2.1.10 Error Conventions 

2.1.10.1 Error Severity 

Errors fall into one of the following categories:- 



Warning 

The function detected a problem but took some remedial 
action which enabled the function to complete successfully. 

Error The function detected a problem for which it could not take 
any sensible remedial action. The system will be able to 
recover from the problem, in the sense that the state of the 
system, with respect to the application remains the same as 
at the time when the function was requested i.e. the system 
has not partially executed the function. 

Severe Error 

The function detected a problem from which the system can- 
not reestablish its state, with respect to the application, at 
the time when that function was requested i.e. the system 
has partially executed the function, and therefore necessi- 
tates the application performing some corrective activity in 
order to restore the system to some known state. 

Unrecoverable Error 

The function detected some problem from which the system 
cannot reestablish its state, with respect to the application, 
at the time when that call was issued and it is possible that 
the application cannot perform some corrective action in 
order to restore the system to some known state e.g. the 
application provides the address of the anchor block which 
the system discovers is apparently corrupted. 
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Severity levels are 16 bit unsigned integers, with the following values:- 



S E VE R I T Y_NOERROR OxOOOO 
SEVERITY_WARNING 0x0004 
SE VERI TY_ERROR 0x0008 
SEVERITY_SEVERE OxOOOC 
SE VERI TY_UNRECOVERABLE 0x0010 



2.1.10.2 Error codes 

WinGetLastError returns a 32 bit value. The format of this value is: 



High uint : 16 bit severity level 

Low uint: 16 bit error code 

The following is a list of errors returned by the window functions. Gpi 
errors are listed for each call. 



The actual codes will be defined later. 



WINERR_I NVAL I D_ SELECTOR 

WINERR_I NVAL I D_ S TR I NG_PARM 

WI NERR_I NVALI D_HEAP_HANDLE 

WINERR_I NVALI D_HEAP_P0 I NTER 

WI NERR_I NVALI D_HEAP_S I ZE_PARM 

WI NERR_I NVALI D_HEAP_S I ZE 

WI NERR_I NVALI D_HEAP_S I ZE_W0RD 

WI NERR_HEAP_OUT_OF_MEMORY 

WINERR_HEAP_MAX_SIZE_REACHED 

WI NERR_I NVALI D_ATOM_TABLE_HANDLE 

W I NERR_ I NVAL I D_ ATOM 

WI NERR_I NVALI D_ATOM_NAME 

WI NERR_I NVALI D_I NTEGER_ATOM 

WI NERR_ATOM_NAME_NOT_FOUND 

WI NERR_I NVALI D_WI NDOW_HANDLE 

WI NERR_I NVALI D_ME S SAGE_QUEUE_HANDLE 

WI NERR_I NVAL I D_PARAMETER 

WI NERR_WI ND0W_L0CK_UNDERFL0W 

WI NERR_WI ND0W_L0CK_0VERFL0W 

WI NERR_W I ND0W_L OCKE D 

WI NERR_WI ND0W_UNL0CKED 

WINERR_NO_MES SAGE _QUE UE 
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3.1 User Interface Shell 



The following sections describe in detail the appearance and function of 
the Presentation Manager User Interface Shell. 

In general, the Presentation Manager Shell aims to present on the screen 
all the functions available in the system. In complete contrast to the sim- 
ple MS-DOS user interface, where very few of the objects and functions of 
the system are visible on the screen, the Presentation Manager Shell can 
show a visual representation of all objects in the MS OS/2 system and the 
functions which operate on them. The approach used is an ’Object- 
Action’ one, where the user selects an object to work with and then 
chooses an action to perform on it. Direct manipulation techniques are 
used by the Shell, such as dragging objects around, and selecting actions 
from pop-up menus. 

One aim of the Presentation Manager Shell is to reduce the need for the 
user to read manuals. In part this is achieved by the user’s ability to see 
all system function on the screen. Another contribution to this aim is the 
consistency of use of the input devices - Keyboard and/or Mouse. The 
user needs to understand only a very few concepts about these devices to 
use the system. An important part of the Shell is the online Help facility 
which it provides - again reducing the need for reference manuals. 

A further important aspect of the Shell is that its user interface 
exemplifies the user interface which should be used by applications. In 
conjunction with the Presentation Manager programming interfaces 
(which the Shell uses), the Shell encourages the consistent end-user inter- 
face which is a prime aim of the Presentation Manager product. 

Consistent with these objectives, the Shell sets out to provide the follow- 
ing capabilities: 

1. Provide structured access to the files found on the user’s system. 

2. Provide a simple, intuitive approach to filing system management 

• high and low level topology/index to the filing system 

• basic manipulation operations (copy, rename, etc.) 

• access to files stored in the system with direct manipulation 
from the mouse 

• visibility of filing system while running applications 

3. Allow for the creation of easy-to-use systems - that is, to provide a 
way to configure a system to allow the naive users to focus and 
work with a predetermined set of applications and files. 



49 




Windows Presentation Manager Reference 



3.1.1 General Features of the Shell 

The basic functions included in the Shell are: 

1. The Screen Layout - Windows 

2. The File Cabinet is the index, viewer, and repository of objects 
related to the user’s data and program storage. Contained within 
the File Cabinet there are: 

• Drives 

• Directories 

• Programs 

• OS/2 files 

• STARTUP (programs) 

The file system is hierarchical - it consists of drives, which contain 
a mixture of OS/2 files and directories. Directories in turn may 
also contain such a mixture, yielding a tree of arbitrary depth. By 
opening a drive or directory in the tree, the user reveals a window 
showing the objects found in that drive or directory. 

STARTUP, contained within the File Cabinet, and allows the user 
to easily manipulate installed applications; for example, Starting a 
program running. 

3. The Task Manager is the window that provides access to, and con- 
trol of, objects that exist in the working environment. In addition, 
it provides general control of the user’s session, defined as that 
period of time that the user is interacting with the system. 

A window in the workspace can easily be brought to the front 
using the Task Manager, by selecting its name from the list 
presented in the Task Manager window. In addition, it may also 
be possible to perform certain other operations on the selected 
task, such as closing it. 

4. The Control Panel allows users to set their workstation 
configuration and other system related parameters. 

5. Printer Services provides output control for any device other than 
the screen. 

6. The Clipboard Viewer is used to view the contents of data in the 
Presentation Manager clipboard. 

7. Startup Editor allows new programs to be defined, and existing pro- 
grams to be changed. 
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These functions are described in more detail in the following sections. 

The initial implementation of the Shell includes direct manipulation in the 
File Cabinet using the mouse. 

The data displayed on the screen is divided into a number of windows. 
Each window encloses the data belonging to one part of the interaction 
between the system and the user. The windows are rectangular and can 
overlap, giving the appearance of papers on a desk top. This means that 
one window obscures the part of another “underlying” window where they 
overlap. 

The screen can have many windows displayed at once. A particular use 
made of windows is the display of menus and dialogs, where the window is 
displayed for a short time while the user makes a choice or inputs some 
data. The window is then removed to avoid cluttering the screen. 

3.1.2 The Pointer 

The Pointer is normally displayed only if there is a mouse attached to the 
system. However, it is also displayed on mouse-less systems at certain 
times to indicate to the user that some particular action is taking place. 
For example, an hour glass is shown to indicate that the user must wait 
while a lengthy operation is in process. 

The pointer is a small shape which reflects mouse movements on the 
screen. The pointer is displayed ’on top’ of the other data on the screen 
and so is always visible. The position of the pointer marks the user’s 
center of interest and activity on the screen. Its position is used when the 
mouse buttons are pressed; for example, to select an item of data on the 
screen. 

The shape of the pointer can vary as it travels over the screen. There is a 
system default shape - an arrow - but each window on the screen can have 
its own pointer shape defined. When the pointer position moves into a 
window which has its own pointer shape, the pointer changes to that 
shape. Similarly, when the pointer position leaves the window, the pointer 
shape changes back to the system shape or to the shape defined for 
another window. 



3.1.3 Selection Cursor 

The Selection Cursor is used to indicate a selectable item that the user can 
select. It is displayed whether or not a mouse is attached and is in addi- 
tion to the pointer. It marks the whole of a selectable item as being the 
center of interest for the user. For example, it can indicate one item in a 
list of menu items which the user wants to select. The Selection Cursor 
can be moved by the mouse or by keystrokes from the keyboard. 
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3. 1.3.1 Selecting Items 

Many items on the screen are Selectable. This means that the user can 
choose the item ( Select it) and then perform an action on this item. 

Selection is performed in a standard way and is not dependent on the kind 
of item involved. The way of selecting an item differs between the mouse 
and the keyboard. Generally, a single item is selected at a time and then 
some function performed. However, in some cases, multiple items can be 
selected and the same action performed on all of the items. Multiple selec- 
tion involves a different way of using both the mouse and the keyboard. 

All these methods are described in the next sections. 



8.1.8. 1.1 Single Selection 



Keyboard 

The user can move the selection cursor around the selectable 
items in the window which has the input focus. This is done 
using the arrow keys, which move the Selection Cursor to the 
next selectable item in the direction indicated by the arrow. 
To move from one group of controls to another, the Tab key 
is used. 

Movement of the Selection Cursor normally involves auto- 
selection of the items. That is, when the Selection Cursor is 
moved, the item onto which the cursor moves is selected and 
the previous item is deselected. 

Mouse The user can move the mouse until the Pointer lies over a 
selectable item and then press button 1 down. The item is 
displayed in reverse video. When button 1 is released, the 
item is selected. Any other item(s) selected are deselected. 

The press and release of the mouse button in this way is 
termed a “click” 

The following action occurs for menu bars and pop-downs. 
The user holds down button 1 and moves the pointer around 
the screen. When the Pointer moves away from the original 
item, it stops being shown in reverse video. If the Pointer 
tracks across other selectable items, whichever item is under 
the Pointer highlights. This allows the user to browse 
around the selectable objects. Whichever item is under the 
Pointer when button 1 is released is selected. If no item is 
under the Pointer, no selection occurs. 

This use of the mouse is termed “press and hold”. 

For other than menu bars and pop-downs, the mouse button 
must be pressed to change the selected item. 
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3. 1.3. 2 Multiple Selection 

In fields with multiple selection (e.g. Check boxes), the following applies: 



Keyboard 

The user can move around the selectable items in the win- 
dow as for single selection. The space bar is used to toggle 
selection of an item, and the Enter key to submit the panel. 

Mouse The user can move the mouse until the Pointer lies over a 
selectable item, and then click button 1. The item is 
displayed as selected, other selections are unchanged. To 
deselect an item, the user clicks on it again. 



3. 1.3. 3 Extended Selection. 

Note that not all windows allow extended selection. Some windows res- 
trict the user to a single selection at a time. This is typical of pull-down 
menus, for example. For those windows that do allow extended selection, 
the following methods apply. 



Keyboard 

To extend the selection of items using the keyboard, the user 
must press the space bar to change from the auto-select 
mode to multiple selection mode. The user can select addi- 
tional items, by pressing the space bar again. 

The mode terminates when Enter is pressed, or the dialog 
cancelled. Whilst the mode is active, the selection cursor is 
displayed independently of selected emphasis, even when 
they apply to the same item. 

To select contiguous items, shift+arrow keys may also be 
used. These do not cause a mode to be entered. 

Mouse The user can press the space bar to switch to multiple selec- 
tion mode, and then click mouse button 1 with the pointer 
over an item to select it. Shift+button 1 may also be used; 
this extends selection from the selection cursor to the posi- 
tion clicked on. 

Double clicking the mouse performs the default action on all 
selected items if in extended selection mode. Otherwise, to 
invoke the default action on all selected items the the user 
must hold the shift key down while double clicking the 
mouse. 
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3.1.4 Use of Keyboard and Mouse 

Keyboard and mouse can be mixed for selecting groups of objects. The 
only exception to this is that direct manipulation of files is not available 
from the keyboard. 

This section describes the standardized actions and their meanings. It 
gives the user a guide to using the Presentation Manager system and the 
programs which run with it. This is done in terms of the keyboard keys 
and mouse actions which can be used and their meanings in terms of sys- 
tem functions. 



3. 1.4.1 Keyboard 

The keyboard keys are divided into several logical sections: 



Alphanumeric Keys 

which include the A-Z, 1-0 and special character keys. These 
are typically used only for the input of data. Corresponding 
characters appear on the screen when these keys are pressed 
and they generally have no other effects. 

Function Keys 

which typically include F1-F12. These are normally used to 
invoke particular actions. For example, Fl has the standard 
meaning of ’Help’ and brings help information onto the 
screen. 

Movement keys 

include the Arrow keys (Up, Down, Left and Right cursor 
movement keys). The Home, PgUp, End, and PgDn keys 
also fall into this class. These are used to cause objects to 
move around the screen. The typical object that they move 
is the Selection Cursor when the user is interacting with a 
list of selectable items. 

Ancillary Keys 

including the Shift, Alt, Ctrl Keys. These are used to modify 
the meanings of other keys. The simplest example of their 
use is to cause the alphabetic keys to produce uppercase 
characters when the Shift key is held down. 

Specific meanings of some of the keys are described below. This list 
includes all those keys with associated functions which are essential to the 
use of Presentation Manager: 
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Alt+Esc 

Jump to next task/program (includes non-Presentation 
Manager programs). This makes the current active applica- 
tion inactive and causes the next task in the Task Manager 
to become active. (Also see the section, “Jump Ordering”) 

Ctrl+Esc 

Jump to Task Manager. Causes the Task Manager to 
become the active window. The Task Manager list window 
is brought to the top. This occurs even if the active applica- 
tion is not in the Presentation Manager screen group, in 
which case the screen group is switched back to the Presen- 
tation Manager screen group first. 

Enter This has two meanings depending on context: 

• Submit the changes. 

• Take the default action on the selected item(s) 

Arrow Keys 

Move Selection Cursor to next selectable item, (selects items 
as it moves, with deselection of previous item(s) - for Auto- 
Select) 

Shift+Arrow Keys 

Extended selection - input field. (Swipe and type) 

Delete Deletes selected text to clipboard, or deletes single character 
to right of insertion point (cursor). 

Backspace 

Deletes character to left of cursor 
Ctrl+Arrow Keys 

Moves to the beginning/end of fields, or words. 

Spacebar 

Toggles selection status of item for multiple selection panels 
and also switches into extended selection mode. 

tab Moves selection cursor between groups of controls 

F10 Toggle to/from (Application) menu bar (same as Alt 
make/break) 

Alt make/break 

Toggle to/from (Application) menu bar (same as F10) 

Shift+Esc 

Bring Up System Menu (or remove, if already shown) 

Alt+F4 Close window (if Close is on the System Menu) 

Alt+F5 Restore window 
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Alt+F7 Move window 

Alt+F8 Size window 

Alt+F9 Minimize window (toggle) 

Alt+FlO 

Maximize window (toggle) 



3. 1.4. 2 Mouse 

The mouse is used in two ways. It can be moved. It has buttons that can 
be pressed. These actions are used in conjunction to provide a powerful 
tool with which the user can interact with the system, using the screen to 
provide rapid feedback. 

Some actions cannot be done with the mouse alone. The shift key on the 
keyboard is used to perform certain actions. The list below shows when 
the keyboard shift key is used. 



Button 1 Click 

Select item under Pointer 

Shift+Button 1 Click 

Extend selection to include items between pointer and previ- 
ous cursor position. 

Button 1 Double Click 

Select item and perform default action. If in extended selec- 
tion mode, add item under pointer to selected items, and 
perform default action on all items. 

Shift+Button 1 Double Click 

Add items to Selection between pointer and previous cursor 
position, and perform default action on all selected items. 

Button 3 Click 

Jump to Task Manager 

Button 3 Double Click 

Jump to next task (Also see the section, “Jump Ordering”) 
Mouse Movement 

Moves the Pointer around the screen. It is used to indicate 
the point of activity or interest in the data presented on the 
screen. 



Button 2 

Application defined meaning - can vary from program to pro- 
gram. 
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Press and hold button 1 

Drag selected object around window or screen. Meaning is 
context and application dependent. 

3.1.5 Functions for Controlling windows 

3. 1.5.1 Appearance of Windows 

All main task windows are surrounded by emphasised borders when shown 
at any size except maximized or minimized. Maximized windows may be 
shown with all borders just off the screen, although conceptually still 
there, but in this case they may not be moved. 

Minimized windows are distinct in that they are shown in iconic form. 
Hence minimized windows do not have normal borders. 

All windows must have a title bar except: 

1. Minimized windows 

2. Maximized windows which need the whole screen 

Minimized windows may be restored by double clicking on the icon. 

The title text of the window is shown next to the icon when it has the 
input focus. 

A single mouse click on a minimized window shows the Systemu. A double 
mouse click (or pressing Enter when the minimized window has been 
selected) will open the icon up to show the program. 

Non-Presentation Manager programs show up as icons in the Presentation 
Manager screen group. A System Menu is shown when they are selected, 
but a screen group switch only takes place when the window is opened for 
use. Thus the user can browse all tasks in the system without constant 
switching of screen groups. Note that if a non-Presentation Manager pro- 
gram is selected in the Task Manager window, then the program is shown 
directly, rather than bringing the icon representing that program to the 
front of the screen. 



3. 1.5. 2 The Shell, Windows and Tasks. 

User input, such as a keystroke, mouse movement or a mouse button press 
is either passed directly to a program, or is intercepted by the Shell. Input 
to the Shell may in turn generate some other input to one or more tasks. 
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For example, a mouse button may be pressed when the pointer is anywhere 
on the screen. This can cause one of the following to happen: 

1. The task deals directly with the pointing. 

2. The input focus is switched to the task’s window and it then deals 
with the pointing. 

3. The Shell deals with the pointing. 



3. 1.5. 3 The Input Focus 

The Input Focus is the place to which keyboard input is directed at any 
time. One window at a time has the Input Focus. The window which has 
the input focus is distinguished by: 

• Being on top of all other windows. 

• Having its window title showing selected emphasis. 

Input focus can be changed either by a mouse Pointer selection in another 
window or by use of the "Switch Task" key, or by using the Task 
Manager. 



3. 1.5.4 Window manipulation - the System Menu. 

The Shell provides a set of functions to allow the user to change the shape, 
size and position of screen windows. These functions are contained in the 
System Menu, which the user can access by selecting the System Menu icon 
(small icon on left side of the title bar) with the mouse, or pressing 
Shift+Esc. The System Menu contains the following functions: 

• Restore 

• Move 

• Size 

• Minimize 

• Maximize 

• Task Manager 

• (optionally) Close 

Applications can add Close to the System Menu if they wish to support 
double click on the System Menu as a fast path to Close an application. 
They must still support Exit on the application menu in this case. Note: 
for default VIO applications the System Menu will contain Close, and will 
also contain Mark, Copy, and Paste. See the section, “Copy and Paste 
for VIO Applications”. 
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3.1. 5.4-1 Z- ordering 

In considering some of these functions, the concept of Z-ordering may be 
useful. It is notionally the third dimension of the screen and accounts for 
the order in which windows overlap each other. The top most window 
visible is the highest in the Z-order; the bottommost is the lowest. In 
terms of pieces of paper stacked on top of each other the Z-order is the 
depth and order of the pile. The Z-ordering also controls the jump order- 
ing of applications. See the section, “Jump Ordering” for details. 



3. 1.5.4 -8 Window Maximize 

An application may define a size to appear when the user selects maximize. 
This size cannot be larger than the screen size, although neither window 
title nor borders need be shown if the application needs the maximum 
screen area. 

To achieve this the user either clicks at the Maximize icon (with button 1) 
on the window title bar, or selects Maximize on the System Menu for that 
window. While the window is maximized, the Maximize icon on the title 
bar is replaced with the Restore icon. Maximized windows may be 
returned to their original size and screen position with Restore, or sized in 
the normal way. (If the window is resized, the Maximize icon is returned 
to the title bar and the Maximize command is reenabled. 

The maximize key (Alt+FlO) toggles. While the application is maximized 
it performs Restore. 

Applications can be run with a smaller screen area, but may be maximized 
at the user’s request. This smaller size might typically not cover the icon 
“Parking-Lot”. (See the section, “The Parking-Lot”) 



3. 1.5. 4-3 Window minimize 

In order to occupy as little screen area as possible, applications may be 
minimized. This will shrink the application to a predefined (iconic) bit- 
map. 

To achieve this the user either clicks on the Minimize icon (with button 1) 
on the window title bar, or selects Minimize on the System Menu for that 
window. When the window is minimized, its appearance is defined by the 
application, but is normally a small bit-map giving a visual clue to the 
program function. When a window is minimized it is moved to the bottom 
of the z-ordering, and the next non-minimized window is made active. 
Minimized windows may be returned to their original size with Restore, or 
double clicking on the bit-map icon. 
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The minimize key (Alt+F9) toggles. It performs Restore while the applica- 
tion is minimized. 

There are two possibilities for where a minimized window goes: 

• to the place it was when last minimized. Minimized windows can 
be moved around the screen like other windows. 

• to the icon “Parking- Lot” . if it was never minimized, 

In either case, minimized windows are never overlapped. They are posi- 
tioned on a notional grid on the screen, and if one position is occupied, the 
next position to the right, (then in row above) is used. 

The position of minimized windows is not related to their position when 
restored. 



8. 1.5. 4-4 The Parking-Lot 

The icon “Parking-Lot” is this notional grid which overlays the screen. 
Each grid segment is large enough to contain exactly one icon; the grid 
starts at the bottom left of the screen, and goes from right to left, top to 
bottom. All icons will be aligned to this grid pattern. 



8 . 1.5. 4 . 5 Change Window Size 

This is achieved from the mouse by pointing at the window border and 
selecting one of the four sides or one of the four corners. 

• If a side is selected, that side may be moved towards or away from 
the opposite side. The opposite side is unchanged. The window 
becomes larger or smaller in one dimension only. 

• If a corner is selected, the two adjacent sides may be adjusted to 
make the window larger or smaller in two dimensions at once. 

In either case, the extent of the new window borders is indicated with an 
outline box which moves with the mouse. When the mouse button is 
released, the window occupies the position and extent indicated by the 
box. 

From the keyboard, sizing is from the System Menu. Changing the size is 
then achieved by use of the arrow keys to move the corner or edge in the 
indicated direction. 

The first up/down left/right arrow kit hit will identify the horizontal 
and/or vertical edge to be moved. 
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This can result in the window borders being moved just off the screen and 
thus becoming not visible. 



3. 1.5. 4 .6 Window Move 

To move a window with the mouse, the "press-and-hold" technique is 
used. The user points anywhere in the window title bar and then drags an 
outline box to where the window is to be positioned. 

The window is redrawn when the mouse button is released. 

Windows may be moved off of the screen to the extent that their title bar 
remains visible. 

From the keyboard, the user selects "move" from the System Menu, and 
then moves the outline box using the cursor keys. The same restrictions 
on window position apply. 



3. 1.5. 4- 7 Restore 

Restore returns the window to its last (unmaximized, unminimized) posi- 
tion and size. 

Size or move operations between maximize or minimize do not affect this 
position. Thus the window can easily be returned to its “normal” position 
using Restore. 

The user either clicks on the Restore icon on the window title bar, or 
selects Restore on the System Menu for that window. For mouse users 
double click on the title bar is a fast path for Restore. 

The position of a window is only “remembered” when it is maximized or 
minimized from some intermediate position. 

3.1.6 File Cabinet - functions for using 
Directories and Files 

The File Cabinet is a major feature of the system for most users. It is a 
program which lets users display and manipulate their file system, includ- 
ing any network connections. The file system is represented visually. 

The File Cabinet provides a range of functions which can be performed on 
these items, such as opening a file (which creates an instance of the 
appropriate application for manipulating that file), moving a file into a 
directory, opening a program (which creates an instance of that program, 
without specifying a particular file to be worked on), copying a file, etc. 
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The File Cabinet and its associated windows are accessible to the user 
while running other applications. This allows the user to locate and 
browse other files at any time. 

Working with files and directories in the File Cabinet would normally be 
through direct manipulation with the mouse. For example, to move a file 
from one directory to another, the user selects the file and drags it to the 
open destination directory. 

Double clicking on an object, or selecting it and hitting Enter will open 
that object, which gives an object-oriented appearance to the system. 

To unify the concepts of a file manager and application manager (for 
starting programs), a special “Startup” window has been created which 
contains directories and programs. Programs may be given long, descrip- 
tive names, yet are viewed and manipulated in the same way as the rest of 
the user’s file system. Information about the user’s file system is presented 
to the user in the form of three types of windows: 

• The File Cabinet Window 

• The Tree 

• Directory Windows 

Only one menu bar is available for the entire File Cabinet. This contains 
two sorts of functions: 

• functions which operate globally on the entire file system 

• functions which operate on the contents of the current directory 

All directory windows are child windows of the File Cabinet window. In 
the File Cabinet, child windows are created slightly smaller than the win- 
dow from which they came, and are slightly offset to the right from their 
parent. Thus if the Tree is sized to be half the area of the File Cabinet 
window, all subsequent directory windows will be slightly smaller than 
that size. If the File Cabinet window is minimized, all child windows tem- 
porarily disappear. If it is maximized, windows already created are not 
affected. If it is reduced in size, all child windows are clipped to the size of 
the File Cabinet. 

Child windows may be sized moved, or maximized (but not minimized). 

The title bar for these windows includes the name of the Drive/Directory 
(truncated if necessary). 

One or more objects may be selected in the list using the normal selection 
mechanisms. 
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The differences between a Directory and Drive are relatively few, with 
some limitations on which actions the user may take on a Drive. For 
example, you cannot move a drive into a directory. Similarly, drives may 
appear based on an explicit action taken by the user to expand the file sys- 
tem - such as by connecting to a remote drive on a network. The things 
that can be done to the contents of Drives and Directories are the same, 
however, so the commands available are identical. 



3. 1.6.1 The File Cabinet Window 

This window contains no data, but represents the maximum screen size to 
be taken up by filing system windows. It has an action bar which provides 
options for the topmost child window. 



3. 1.6. 2 Tree Window 

This window consists of a main area with a representation of the drives 
and directories in the system. It has no menu bar, and its size is limited 
by the bounds of the main File Cabinet window. 

On the left of the main area, each drive in the system is represented by an 
icon in the shape of drive or diskette, accompanied by the disk volume 
name. 
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Figure 3.1 The File Cabinet with Tree 

The drives are arranged in a single column in alphabetical order of drive 
identifier (Startup at the top). If there are too many drives to appear 
simultaneously, scroll buttons appear at the top and bottom of the visible 
portion of the column of drive icons. These allow other drives to be 
scrolled into view by the user. 

To the right of the drive icons is a column of directory names. These are 
visually grouped and linked back to one of the drive icons by a series of 
lines or braces. The column of directories represents all the first-level 
directories belonging to the root directory of the disk represented by the 
selected drive. 

If there are too many directories to fit in the window, scroll buttons 
appear at the top and bottom of the visible portion of the column. These 
allow other directories to be scrolled into view by the user. 

Deeper levels of the directory tree may be displayed in the Tree window by 
selecting the containing directory or drive with either the mouse or key- 
board. Mouse selection is done by clicking on the appropriate drive or 
directory. Keyboard selection is done by moving the selection with the 
arrow keys. The user selects the drive or directory to be displayed with up 
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and down keys. Hitting the right arrow key causes the next level of the 
tree to be revealed, and the first directory in that level to be selected. Hit- 
ting the left arrow key causes the current level of the tree to be hidden. 
Pressing alphabetic keys causes the selection to jump to the next directory 
that matches the key in that level; the next level of directory is displayed, 
as if right arrow had been hit. 

The up/down arrows always remove any tree displayed at a deeper level. 

PgUp and PgDn scroll the current directory level by a screenful. Home 
moves to the top of the current directory level, and End moves to the bot- 
tom. 

As with the first-level directories, subsequent levels of the tree are linked 
visually with their parent directory or drive by lines or braces. Each 
column will have its own scroll buttons as required. 

The directories may be nested so deeply that all the columns of directories 
cannot be shown in the window simultaneously. In this case, a horizontal 
scroll bar appears at the bottom of the directories window. This can be 
used to browse the whole of the directory structure. 

No files are shown in the Tree window. The files and directories belonging 
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to a directory can be displayed in a directory window. 

3.1.7 File Cabinet functions 



3. 1.7.1 The File menu 
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Figure 3.2 The File pull-down 



The File menu includes: 



Open opens a new window containing the selected drive or direc- 
tory. The new window is displayed slightly offset from the 
Tree window, and on top of (first in the Z-ordering) all other 
windows. Windows showing directory contents are created 
based on the size of the window from which they were 
created. If a window containing the drive or directory 
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already exists, a new window is not created. Instead, the 
existing one is brought to the top. 

The Open command is the default action for the File Cabinet 
window, hence double clicking an item, or hitting enter with 
an item selected will cause that item to be Opened. 

• If the selected object is a directory, the new window is 
simply another directory window, containing the con- 
tents of the selected directory. 

• If the object is a program, the new window contains 
another instance of the selected program. 

• If the object is a file, and there is a default action 
assigned to the file then the default action is taken. (For 
example, .SCR might be input to a script program, when 
opening a .SCR file would run the script program with 
the particular .SCR file as an input parameter.) 

If there are multiple default actions assigned to a file 
type (extension), an intermediate window appears with a 
list of the actions. The user is allowed to select one of 
the actions, the window disappears, and a new window 
belonging to the selected action appears. 

Windows other than directories are not confined to the File 
Cabinet, but have a size and position determined by infor- 
mation stored with the program being invoked. If multiple 
items are selected when Open is requested, the shell assumes 
that the intent of the user is to use all of the items simul- 
taneously. Thus all the items are opened. Any dialog boxes 
are shown sequentially. 

Print causes the selected objects to be printed. If there is no pro- 
gram assigned to the object, then the object is printed as a 
text file. If there is a program assigned to the file extension, 
the program is invoked. Programs may provide a special 
invocation option for printing. 

Move This command is provided for users who need to move files 

across drives and directories. It brings up a dialog box which 
contains two text entry fields. The first (F rom:) contains 
the names of the objects to be moved. When the dialog box 
first appears, this field is filled with all selected directories 
and files in the File Cabinet window. The user can then type 
additional names. Multiple filenames are allowed in the 
From: field, and standard wildcard syntax is valid. The 
second field (To:) contains the name of the destination. It is 
initially blank. 

The user completes the move by typing in the name of the 
target file or directory and hitting Enter. Leaving the field 
blank implies the current directory (see Create Directory for 
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a description of the current directory). 

If the user types into the From field, the typed text is added 
to the pre-filled text. The pre-filled text can be deleted. 

It will be verified that there will be enough disk space before 
attempting the actual move or copy, so as not to risk run- 
ning out midway through the operation. 

Copy This command is identical to the Move command, except 
that it makes a second copy of the data. 

Copy is also available by direct manipulation in a similar 
way to Move, but holding down the Alt key as well as the 
appropriate Move key(s) 

Delete brings up a dialog box with a single text edit item, contain- 
ing all currently selected items. The user can then type 
additional items. When the user confirms the delete, all 
items described in the text entry field are erased. 
Confirmation is by pressing Enter, or clicking on Delete. 

Certain erase actions (drive contents, for example) cause 
further dialogs to confirm the operation, or ask for more 
details. 

Rename This is used to change the name of a file, directory or file. 
Only a single file can be renamed. 

Set Properties 

allows the user to set the attributes of an object. The MS 
OS/2 file system attributes that may be changed are the 
read-only and/or archive bits, or the time and date infor- 
mation. Directories cannot be changed. 

Create directory 

This allows new directories to be created. The command 
brings up a dialog box to prompt the user for the name. 

The directory is created in the current directory, which is the 
topmost window in the File Cabinet. 

1. If the topmost window is the Tree, and only a drive is 
selected, it is the root directory of that drive. If it is 
showing some other directory selected, the current direc- 
tory is the one shown selected. 

2. If the topmost window in the File Cabinet is some other 
directory, then this directory represents the current 
directory in MS OS/2 terms. 

Select all 

Selects all objects in the current window. It is not valid in 
the Tree window. 
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3. 1.7. 2 Direct manipulation 

Using the mouse, a completely different method of moving files and direc- 
tories is available. The user selects an object to be moved, holds down 
mouse button 1 over the object, and drags it to a previously opened direc- 
tory window. When the button is released, the object is moved to this new 
directory. 

Both the source object and part of the target directory must be visible. 
Objects may be dropped anywhere within the target directory with the 
same effect. 

Both source and target directories are redrawn after the object has been 
moved. The details of the move are as for the keyboard version, with the 
same error situations, but with an additional error when the target is not 
a valid directory window. 

Multiple objects may be moved by extending the selection in the usual 
way, and then holding shift while dragging. Alternatively, if the space bar 
has been used to switch to extended select mode, then multiple objects will 
be dragged without the use of Shift. 

Pointer appearance during the move is that of a file, or directory, or a 
group of objects for extended selection. 



S. 1.7. 2.1 Summary of Mouse use in Direct Manipulation. 

The following section details the rules for keyboard and mouse interaction 
for direct manipulation in the File Cabinet. 

The default direct manipulation operation in Presentation Manager is a 
move on a single object. In order to perform a non-standard move opera- 
tion or standard/non-standard copy operation some interaction is required 
with one or more of the following keys. 



ALT key 

This changes the operation from a move to a copy. 

CTL key 

This is used to add an object to a non-contiguous set for a 
group copy /move operation. 

Shift key 

This is used to add an object to a contiguous set for a group 
copy/move operation. 
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Below is a glossary of terms used in the following set of rules 
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3. 1.7.3 Options menu 
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Figure 3.5 The Filing system with Options pull-down 



The options menu applies to the active child window, and (optionally) to 
windows subsequently created in the filing system. 

Windows previously created are not affected by changing these options. 



Display Options... 

The Display Options dialog includes 

1. Include', which directories and files to display - the user 

can set this according to all valid attributes: 

• Name or extension - via wildcard filters 

• Type - directories, programs or files (check boxes). 

• File attributes - normal or special check boxes. Spe- 
cial shows a panel with hidden, read/only, system, 
archive check boxes. These selections show only 
objects with all the chosen bits set (and which qualify 
by the other selection criteria). 
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The objects displayed are the logical intersection of each 
of the groups selected. The defaults are *.*, all direc- 
tories, files and programs, and normal. 

2. Display order, what information the objects should be 
sorted on: 

• Name 

• Extension 

• Type (directory, program, or file) 

• Size 

• Date/time 

3. What to display: Name, date, size and attributes. 

This allows the user to set the way that the contents of 
directories and drives are displayed. 

Name only 

An extra choice is provided on the first menu as a fast path 
to the display of as many objects as possible. When Name 
Only is selected, the other options for what to display are 
ignored, and only the names are shown. The choice toggles. 

The name is always displayed. When “Name-only” is 
selected, objects are displayed in multiple columns, with a 
horizontal scroll bar appearing if there is insufficient window 
space to display all objects. Otherwise, the objects are 
displayed in a single column, possibly with a vertical scroll 
bar. 

File options 

toggles whether certain confirmation messages are displayed. 

• Verify on Copy - compare the bytes in files after a copy 

• Verify on Delete - show the dialog box on all delete com- 
mands 

• Replace existing file - give warning prompt 

• Sub-Tree Delete - delete a directory (and everything in it) 
even if the directory is not empty 

Show Information 

toggles whether information about the drive or directory is 
displayed. The state is indicated by the presence of a check- 
mark (on) or its absence (off). If off, no information is 
displayed. If on, the following is displayed: 

• Space used by files shown (files that have passed filter), 
out of total on disk. 
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• Number of objects visible in window OF total number of 
objects (files and directories). 



3. 1.7.4 Special Menu 
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Figure 3.6 The Filing system with Special menu 


The Special menu includes commands which operate globally 
system or diskettes. 


on the file 



Format This allows the user to format new data diskettes. The com- 
mand brings up a dialog box with a text field which requests 
the drive letter (with a logical default shown as selected, the 
drive name, and checkboxes which allow the user to select 
format options such as: 

• format single/double density. 

Format prompts the user for a volume label and other 
options in a dialog box. 
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Refresh Ensures that the File Cabinet windows are all up to date. 



3. 1.7. 5 The Window menu 
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Figure 3.7 The File Cabinet with Window pull-down 



F6 The next directory in the currently displayed directories is 

brought to the top of the child windows and given the input 
focus when F6 is hit. 

Directories are removed by closing them using their System 
Menu/icon. 

1 Tree The Tree window is given the input focus and brought to the 
top of the child windows in the File Cabinet 

Directory list 2..n 

A list showing the child windows in the File Cabinet is 
shown in the pull-down window. If there are more than 8 
directories, an option to list all the directories replaces the 
ninth. 

The name shown is the full name of the directory displayed. 
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For the root directory it is the drive identifier and backslash. 

The names of Startup program directories are truncated to 
40 characters. 

Close All Directories 

This commands closes all existing directory and drive win- 
dows, providing an easy way for the user to clean up the File 
Cabinet windows. 



3.1. 7. 6 STARTUP window 

The Start-A-Program functionality of MS OS/2 is represented by a special 
STARTUP icon which appears in the Tree window along with the other 
Drives. Its functions and operation are essentially the same as any other 
directory window, with some exceptions: 

• Directories are represented by program Groups. 

• Activities must be added to STARTUP using a special application 
called the “STARTUP- Editor” . This includes the ability to install 
an activity into the list, or modify an installed entry. This file is 
available in the File Cabinet by selecting the “STARTUP Editor” 
from the list of programs in STARTUP. Applications may also 
add themselves to STARTUP during installation. 

• Entries in the STARTUP list can only be moved within STARTUP. 
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Icons - S = System Menu 



N = Minimize, X = Maximize 



Figure 3.8 The File Cabinet with STARTUP panel 

8. 1.7. 6.1 STARTUP Functions 

The File menu functions are: 



Open Causes selected STARTUP program to be run, or a group to 
be opened. 

Copy Works only within STARTUP, but is otherwise similar to 

normal Copy. Only one program or group may be copied at 
a time using this method. Names may be fully qualified 
using “\” 

Direct manipulation works with the STARTUP programs 
and groups, and does allow multiple items to be moved and 
copied. 

Move Used only to move between groups in STARTUP. Similar to 
Copy. 

Rename Used to change the long name of a program. 

Delete Deletes the reference to an application from the directory. A 
warning is given if this is the last reference to an executable 
file. 

Create directory 

Creates a new group of applications in STARTUP 

Select all 

Selects all activities in a group. 

In the other pull-downs, File Options is available, plus all the Window 
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options. All other options in pull-downs are grayed. 

In the Tree, application names are displayed as the full length of the text 
(no trailing or leading blanks). The column widths are adjusted to sup- 
port the longest entry in that group. 

In windows showing the contents of program groups, the names of pro- 
grams and groups are displayed in a single column. No other information 
is shown, apart from the directory/program icon. 

3.1.8 STARTUP Editor 

Most programs in Presentation Manager are added to the system using the 
standard installation process. The STARTUP Editor is only needed for 
those programs not installed in this way. 

The STARTUP Editor is available from the File Cabinet, and allows users 
to add or modify an entry in STARTUP. The STARTUP Editor consists 
of a main window which includes entry fields that the user enters the 
relevant program invocation data, including: 

• Program type (Radio button choice) 

• Icon file name. 

• Executable file name and directory 

• Working Directory at invocation 

• Parameters. This will have a syntax which allows prompting. 

• Two-line description of the application (also provided during 
installation) 

• Environment variables 

• Program name for STARTUP 

• Group in STARTUP 

The last two items are prompted for by Save As... 

The information supplied is stored in the PRESSERV.INI file. 

All of the information which can be edited here is given initial values 
automatically during installation. 



77 




Windows Presentation Manager Reference 



Si 


-T- STARTUP Editor 


|N|X 


File 


Edit Exit 


Fl=Help 



Path/Program name . . . - 

Icon file name - 

Parameters - 

Working Directory. . . - 

Environment - 

Description for Help- 



-Program Type- 



| (.) OS/2 PM ( ) VIO 

] ( ) Protected Mode ( ) Real Mode 



Icons - S = System Menu N = Minimize, X = Maximize 

Figure 3.9 Startup Editor - main panel 
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Icons - S = System Menu N = Minimize, X = Maximize 



Figure 3.10 Startup Editor - File pull down 



The File menu includes: 



New This command clears the any entries in the STARTUP Edi- 
tor window and resets any default fields. 

Open This command is used to load a previously defined 

STARTUP entry. A dialog is displayed which allows the 
user to selected the entry from a list box. 

Save This command is used to save a STARTUP entry. If a name 
has not been supplied a dialog is displayed which prompts 
for a name, otherwise the information is simply saved. 

The group name is prompted for in a similar way. 

Save As This command is used to save a STARTUP entry with a 

given name. A dialog is displayed with an entry field which 
prompts for the name. If the program already has a name, it 
is proposed as the default. 

The group name is prompted for in a similar way. 
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Figure 3.11 Startup Editor - Edit pull down 



The Edit menu includes: 



Cut Removes the currently selected text and places it on the 
Clipboard. 

Copy Places a copy of the currently selected text on the Clipboard. 

Paste Inserts the current text contents of the Clipboard in the 
selected field. 

Clear Removes the currently selected text, but does not place it on 
the Clipboard. 

Undo Regress the last change. 

3. 1.8.1 The Exit menu 

This command quits the STARTUP Editor. If any changes have been 
made to the entry’s information since the last save, a message will be 
displayed informing the user that there are unsaved changes and request- 
ing whether to save changes. If the user responds Yes (the default), then 
the Save As dialog box is displayed, if not, then the STARTUP Editor 
ends. 
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3.1.9 Task Manager 

Presentation Manager is capable of running many tasks at the same time 
These programs can all potentially be using the screen at the same time. 
The user needs to be able to identify which tasks are running and to con- 
trol which tasks are visible on the screen at a given time. The user also 
needs to close the system down at the end of work. 



3. 1.9.1 How to Access The Task Manager. 

The Task Manager is a window, which appears in the Presentation 
Manager screen group, that contains a list of the user’s current activities. 
The user brings the Task Manager window into view by hitting button 3 
on the mouse, hitting Ctrl+Esc on the keyboard, or by selecting the Task 
Manager command from the System Menu of the current application. If 
the Task Manager is called up while the user is in a non-Presentation 
Manager screen group, an implicit screen group switch is performed, and 
the user sees the Task Manager in an otherwise empty workspace. 

The Task Manager normally contains a representation of every indepen- 
dent task running in the system. The representation is in text form, where 
the text is provided by the object, and typically matches the text 
displayed in the caption of the object (file name + data name). 

The default Task Manager window size is large enough to display approxi- 
mately 10 objects. A vertical scroll bar is displayed and can be used to 
move the list of objects, allowing every object in the Task Manager to be 
viewed, even if not all objects fit within the window. The object last 
worked on is selected and the list is scrolled to show the selected item at 
the middle of the window (unless the first or last item is visible in the win- 
dow). 

The appearance of the Task Manager window with several tasks running 
might be as follows: 
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Figure 3.12 The Task Manager window 

The objects in the Task Manager are ordered alphabetically. 
The entries in the Object List are selectable. 

The System Menu commands include: 

• Switch to 

• Close (Same as Exit being selected in application) 

• Terminate 



3. 1.9. 2 Jump Ordering 

The jump order round applications is their Z-order on the screen. Appli- 
cations can optionally not participate in the jump sequence, but normally 
all applications will participate. 

Non-Presentation Manager applications appear as icons in the Presenta- 
tion Manager desktop, and so have a logical entry in the jump order 
sequence. Using the keyboard or mouse to jump to the next application 
will make the icon representing the non-Presentation Manager program 
active. To see the program itself the icon will have to be Opened. Note 
that if the corresponding entry in the Task Manager window is selected 
that the icon is automatically opened. 
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Figure 3.13 The Task Manager window with Control pull down 



3. 1.9. 3 How to Work With a Task. 

The user can choose to work with a particular task by: 

1. Selecting the Name of the task in the list. 

2. Select the Switch To command on the Control menu. 

The fast way of getting a task to be the Active one is to do a doubleclick 
on it with button 1 or select it and press Enter. 

The selected task becomes the Interactive Program. 

Certain tasks can cause the Switch To selection to be grayed. 

Alphanumeric keys can be used to move the selection to an object on the 
list when the first letter of the name matches the key pressed. If there is 
more than one match the selection moves to the first. If the same key is 
pressed again, the selection moves to the next and so on, recycling at the 
end of the matching section to the top. If no match is found, the machine 
beeps. 

For Presentation Manager tasks, this causes the main window of the object 
to appear on top of the other windows in the Presentation Manager screen 
group. The application may choose to bring its other windows to the front 
at the same time. Keyboard input is directed to one of the windows 
belonging to the task. 

For Non-Presentation Manager programs, the Presentation Manager 
Screen Group is removed from the display and is replaced by the Screen 
Group containing the program. This occupies the whole screen and no 
other programs can be seen. Both Mouse and Keyboard input are directed 
to the program. 

Non-Presentation Manager programs also show up as icons in the Presen- 
tation Manager screen group. 
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3. 1.9.4 How to Close a Task 

Some programs will not have a Close(Exit) command. The user may use 
the Close command to close these objects. This commands requests that 
the program close down normally (save data, clean up). 



3. 1.9. 5 How to Terminate a Task. 

Most programs have their own methods of being brought to an end nor- 
mally, through menu options or commands. Generally the user should use 
these methods to terminate a running program. This is advisable because 
the program probably needs to tidy things up before it finishes - save work 
away in files, for example. 

However, it can happen that a program gets stuck or begins to behave in 
an unusual way. To allow the user to stop such a program, the Terminate 
function can also be used quit a program. When invoked the Terminate 
function causes a destructive shutdown, i.e, the program does not get a 
chance to save data or otherwise clean up. 

To terminate a program in this way, select the program’s entry in the 
Task List and then select the Control option in the Task Manager menu 
bar. Select the Terminate option on the pull-down menu which appears 
as shown in. A warning panel is displayed. This allows the user a second 
chance to think about the destructiveness of the Terminate function and 
prevents inadvertent program stopping. 

The filing system window cannot be closed or terminated. 
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Figure 3.14 Task Manager - terminating a task 
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Either the Yes or No buttons must be selected. The default button is No 
(for safety), in case the user presses the Enter key as the first action after 
this panel appears. 

Selecting the No option quits the Stop operation and leaves the program 
running. 

Selecting the Yes option causes the program to be stopped. 



Figure 3.15 Task Manager with Shutdown pull down 
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The Shutdown menu includes: 



Shutdown now 

This is the normal way to close the system down at the end 
of the work session. There are two variations, controlled by 
the next option in the menu. 

1. Save at shutdown on causes Shutdown-now to save the 
entire task list in terms of the applications running, and 
their position on the screen. Each application is respon- 
sible for saving its data and current state. 

2. Shutdown with Save at shutdown off causes all appli- 
cations to end normally but no record is kept and Res- 
tarting the system will not restart the current set of 
applications. Before an application ends, it is expected 
to prompt the user to save any unsaved changes, and 
then to shut down. 

Save at shutdown 

This toggle indicates the current action to be performed at 
shutdown. It is initially set off (no save). 
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Save tasks now 

This provides the user with an easy way to save the layout 
and data ready for the next IPL. This includes notifying 
applications so that they can be restored at least working on 
the same file at the next IPL. Screen window layout and 
current options must also be preserved. 

No shutdown is performed. 

The Task Manager window is removed from the screen only following a 
Switch To operation. 



3.1.10 Control Panel 

There are many options the user has for how the system works. Most have 
to do with the hardware configuration, while others have to do with the 
Presentation Manager system’s appearance. Control Panel allows the user 
to change these settings: 
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Figure 3.16 Control Panel 



3.1.10.1 Main panel 



Time & Date 

The user can set the time and date (Entry fields). This will 
set the internal hardware clock. 
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Double click 

The double click rate is the time interval within which indi- 
vidual mouse clicks must be received in order to generate a 
doubleclick. 

Cursor Blink: 

This changes the rate at which the caret flashes. Cursors 
which flash too quickly tend to be distracting, while if they 
are too slow, then they are hard to spot. 



3.1.10.2 Preferences pull down 



Sound On or Off 

Allows the user to turn off sound (Check box) 

Screen Colors 

The user can select which colors are used in various parts of 
the system. For example, the items below can be changed. 
This list is not considered to be exhaustive. 

— Window Background 

— Window Text 

— Scroll Bar 

— Scroll Arrows 

— Scroll Elevator 

— Active Title Bar 

— Inactive Title Bar 

— Title Bar Text 

— Window Borders 

— Menu Bar 

— Menu Text 

— Screen Background 

Border sizes 

The user is able to select border width. Novice users may 
want wider borders to make it easier to manipulate the bord- 
ers directly. More experienced users may want to shrink the 
borders. 

Logo on/off 

The user can suppress all logo displays. Default is no 
suppression. (Check box). 
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Mouse Buttons 

Right handed people tend to want their mouse buttons from 
left to right (1-2-3), whereas left handed people want the 
opposite (3-2-1). Control Panel allows the user to select 
which he or she wants. 



3.1.10.3 Settings pull down 



Printer drivers 

Options to select additional printer drivers (Entry field) 
Printer defaults 

Options to select default printer and settings (List boxes) 
Print spooler 

Options to select spooler (Entry field) 

Communications 

Options to select Baud rates etc. (Entry fields, radio buttons) 
Ports Options change Comml etc. (List boxes) 

For further information see the section, “Spooler and Printer 
Configuration” in the chapter, “Spooler Interface”. 



3.1.10.4 Configuration pull down 



Global data. 

In the Presentation Manager system, "PRESSERV.INI" is 
not a text file, and if the user’s system configuration 
changes, it is not possible for the user to edit the changes 
into "PRESSERV.INI" with a text editor. Therefore, the 
Control Panel must account for all such possible hardware 
changes. This includes changes to CONFIG.SYS. This 
includes changing the type ahead buffer size, and the 
autorepeat rate of the keyboard (this is configurable on the 
AT). The more commonly changed options are shown indivi- 
dually with entry fields, others are shown in list boxes. 

For full details of the contents of CONFIG.SYS and an 
explanation of what each entry means the user should con- 
sult the MS OS/2 Setup Guide. 

Path: The user can set the initial path for the system. 

Fonts: It is possible to purchase new fonts for Presentation Manager 

and to tell Presentation Manager that they exist. 
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International Settings: 

The user can change the time/date format, the currency 
symbol, and other international characters. 

Default action definitions. 

The default Open action and Print action may be specified 
according to file extension. The panel allows this for each 
file extension the user wishes to define, plus a default to be 
used by others, or the option to disallow certain file exten- 
sions. 

When applications are installed, they may wish to prompt 
the user as to whether they should appear for certain file 
extensions. 

List boxes and entry fields allow this. 

Miscellaneous system variables: 

Users can change any system variable through the control 
panel. Applications can define variables in the initialization 
file themselves, and list boxes and entry fields will be avail- 
able to change these. 

3.1.11 Clipboard Viewer 

Presentation Manager provides copying and moving using the cut, copy 
and paste metaphor. This allows an object/action approach to be applied 
to copying, rather than the action/object approach of "copy what, to 
where". 

To the end user, the appearance of cut and paste is as follows: 

1. Mark the object to be copied or moved by the normal selection pro- 
cess. 

2. Choose either cut (to remove it from the file to the clipboard), or 
copy (to copy it). In entry fields, cut may be performed using the 
Delete key, and Copy using Ctrl+Insert. 

3. In the target file (which may also be the original file), select the 
target position. 

4. Select paste. In entry fields, Paste may be performed using 
Shift+Insert. This replaces selected text with the clipboard con- 
tents. 

Typically, these functions are provided on an Edit menu in each applica- 
tion (As in the STARTUP Editor), and the user can use them both inside 
and between applications. 
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The Clipboard viewer provides the user with an easy way to look at the 
contents of the clipboard. As objects are cut and copied to the clipboard, 
the Clipboard Viewer displays the object type and the object itself. The 
Clipboard Viewer understands several predefined formats: 

• Text 

• Rich Text 

• Bitmaps 

• Metafiles 

The Clipboard Viewer menu contains: 



Clear Allows the user to empty the clipboard and free up any 
memory used by the objects in the clipboard. 



3.1.11.1 Clipboard mechanics. 

To create this easy-to-use environment, the clipboard is set up to accept 
any number of different data formats, several of which it can hold simul- 
taneously. 

When a new application wants to copy the data, it looks at the data for- 
mats available, and chooses one that it understands. 

The data itself may be in the clipboard already, or it may be sent as the 
result of a message from the target application to the source one. 

Applications should use standard IBM data stream definitions, since these 
will be supported by printers, plotters and editors. 



3.1.11.2 Copy and paste for VIO applications 

A simple form of cut and paste is provided for default VIO applications. 



Copy Areas of screen can be MARKed with an option available 

from the System Menu, and the contents of the marked area 
copied to the clipboard in text format. 

Paste will replay text as if it were being keyed into the application. 
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3.1.12 Initialization 



3.1.12.1 The initial view of the system 

The view of the system when it is IPLed for the first time is that of the 
File Cabinet with the root directory of the default drive displayed in the 
Tree. 

Also displayed is an open directory showing the root level of STARTUP. 

This view will remain the initial view until it is replaced by the user saving 
the current tasks. 



3.1.12.2 The Initialization File 

The initialization file, called PRESSERV.INI, is a Binary file - i.e. it is not 
human readable and cannot be changed easily using text editors. The file 
is hidden, since it is not intended for direct use by end-users. Its use is 
mainly by the Presentation Manager system, which does provide some API 
functions for reading and changing its contents. (See the section, “Presen- 
tation Manager Initialization File Functions”) 

The initialization file contains all non-volatile task information. This 
includes files installed in STARTUP, open directories and running files, 
and system defaults for both MS OS/2 and Presentation Manager. 

The system will boot without the initialization file, but default system set- 
tings for colors, display device etc., will be used. 

If errors are detected within PRESSERV.INI, the system will attempt to 
function correctly, but some strange behaviour may be noticed. For exam- 
ple, applications that the user knows have been installed not known to 
STARTUP. The user will be informed of the errors, whereupon it might 
be necessary to restore the system from a backup copy. 

On network systems there may be a local copy of PRESSERV.INI but a 
global copy of Presentation Manager. 



3.1.13 HELP facility for the shell. 

The purpose of Help is to provide information to the user which aids in the 
operation of the shell. When the user requests Help, information regard- 
ing the item selected in the current context is displayed. The user can also 
request an index of available Help topics, request General Help, or request 
information on the functions assigned to keys. 
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3.1.13.1 INVOKING HELP 

The user can request Help by either pressing the Fl key, or by clicking the 
mouse pointer while it is on the Fl=Help choice on the Action Bar. After 
doing one of these actions, a secondary window will be displayed, and it 
will contain a panel of information which pertains to the item on which 
the selection cursor is currently positioned. 

Note that more than one item may be selected on the panel, but the initial 
help will relate to the item where the selection cursor is situated (generally 
the last item selected). 



3.1.13.2 THE HELP WINDOW 

The Help window is moveable and sizeable, and will be the topmost win- 
dow when it is active. It contains four pushbuttons along its bottom, and 
these make up the Common Actions Area. There is also a vertical scroll 
bar along the right side of the window, and this can be used to scroll the 
Help panel which is displayed in the window if it is too big to fit. If the 
window is sized smaller than its default size in the horizontal direction 
then the text is clipped, there is no horizontal scroll bar. The window 
must be resized to display the full text. 

In the window’s title bar appears the application name. Here is a picture 
of a typical Help window: 
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Figure 3.17 A sample help window 



3.1.13.3 HELP INTERACTIONS 

When a help panel is displayed in the Help window, the user can either use 
the mouse to scroll the text with the scroll bar, or can use the arrow keys, 
Home, End, PgUp, PgDn, Ctrl+Home, and Ctrl+End keys to scroll the 
text. 

The pushbuttons at the bottom of the window, in the Common Actions 
Area, perform the functions described below. The user can perform the 
actions by either pressing the pushbutton with the mouse pointer, or typ- 
ing the key whose label is on the desired button, ie. Fl, F5, F9, Esc. 
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8.1. IS. 8.1 Fl=General Help 

Displays a general Help panel describing what the panel is for and the con- 
cepts behind it. This is not help on the Help facility. 



8.1.13.8.2 F5=Index 

Displays a selection panel (or listbox for simple applications) which lists 
all of the available Help topics. The user can select a topic from the list, 
and it will be displayed. When the listbox is displayed, the F5=Index 
pushbutton changes to read Enter. The user can select a topic by either 
pressing the Enter key, pushing the Enter button, or doubleclicking the 
mouse on a topic in the listbox. When the listbox is removed, the Enter 
pushbutton is changed back to read F5=Index. 



3.1.18.8.8 Shell Help Index 

For each of the Presentation Manager Shell “Applications” 

• File System 

• Task Manager 

• Control Panel 

• StartUp Editor 

• Clipboard Viewer 

• Printing Services 

the HELP index will contain the following - 

• A list of all the available HELP topics for the application 

• An item to select help on the System Menu 

• An item to select help on general controls (E.g. Scroll bars ) 

• An item that states that general help is available from the File 
Cabinet Help Index 

In the File Cabinet as well as the above items there will be a list of Global 
Topics, e.g. Setting screen colors, Printing files.... which will contain a 
brief description of how these things can be done and say which applica- 
tion needs to be started. 
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8 . 1 . 18 . 8.4 F9=Keys 

Displays a Help panel describing the functionality of all the keys available 
to the application (without Help displayed). 

If the user asks for help on keys while in an application, the help will 
display the key functions for that application. The user will be advised 
that the application must be the interactive window before the keys will 
work as defined in the panel. 



8.1.18.8.5 Esc=Cancel 

Removes the currently displayed help window. 



3.1.13.4 Additional notes about Help 

If there is no selection cursor when Help is requested, a general Help panel 
providing information about the currently active window will be 
displayed. 

When the Help window is displayed, it becomes the interactive window. 

During pull-down interaction with the mouse, Help must be selected using 
FI. 

The Help panel exists until it is removed by the user, or its containing 
application is closed. 

If the application is minimized while Help is being displayed, the Help 
panel is removed. If the Help panel is required when the application is 
restored, Fl must be pressed again. 

Help is available by hitting Fl while a Window is minimized and has the 
input focus. Help for the System Menu will be displayed which will contain 
help on how to restore the window. 

Help panels are not constrained within the application main window. 
Examples will be included on Help panels where appropriate. 



3.1.13.5 Help on items in STARTUP 

A two-line description is supplied with applications, and automatically 
included at installation. It may be edited using the STARTUP Editor. 
This brief application help will be displayed if Help is requested in the 
File Cabinet while an application is the selected item. 
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No index is provided for this Help. 



3.2 The User Interface Shell API 



All of the User Interface Shell functions that are available to the end user, 
through interaction with the Shell using the mouse and keyboard, are also 
available to an application program using the User Interface Shell API. 

The API functions provided are listed and described below. The lists of 
functions are divided into functional areas that are similar to those for the 
description of the interactive components of the Shell given above. 

3.2.1 Definitions of terms used in the Shell API 

The Shell API introduces a number of unique terms and concepts which 
require definition, and those definitions are collected together in the fol- 
lowing list. 

Application Information File This file, usually provided as part of an 
application package, provides a simple way for a programmer to describe 
his “program” in a way that is acceptable to the Presentation Manager 
system. The file is an ASCII text file, which can be edited using any of a 
number of available Line- and Full-screen-editors, including EDLIN. 

The file contains a (relatively) free format description of an executable file, 
or files, the title required for the program, a description of its parameters 
and so on. 

The Shell API provides a function, WSHLoadAIF, which can read these 
files and convert the contents into a fixed format data structure in 
memory. This data structure is used as input to the WSHAddProgram 
and WSHChangeProgram functions in order to create or change the 
program’s entry in the Installed Program List. 

The AIF file format is as described in the MS OS/2 Reference with regard 
to the PIP language. If a user wants to create an AIF and use that as a 
program definition file, Presentation Manager will use the AIF as long as it 
follows the definition laid down by MS OS/2. 

Executable File The fully qualified name of the file that is executed when 
this program is run. 

Executable files can be “.BAT” files, “.CMD” files, “.COM” files or “.EXE” 
files. Note that Presentation Manager can only start protect mode pro- 
grams and will not be able to start real mode programs. 
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It is permitted for several entries in the Installed Program List to refer to 
the same executable file. This might be done if the same program is to be 
used with different (fixed) parameters at different times. 

Group Information Structure This is a data structure which is used to 
return information to the caller of the WSHQueryProgramTitles function. 

The format of the Group Information Structure is defined in the descrip- 
tion of the WSHQueryProgramTitles function. Program Information 
Block This is a data structure which is used to contain a representation of 
all of the information stored in the Installed Program List about a single 
program. 

The data structure is used to return information from the 
WSHQueryDefinition function, and to provide information to the 
WSHAddProgram and WSHChangeProgram functions. The format of the 
Program Information Block is defined in the description of the 
WSHAddProgram function. 

Handle In general within Presentation Manager, a Handle is a 32 bit 
value. It provides an identifier to an object or resource being used by the 
owner of the handle. 

Icon File Name When a program is started, the Icon that is to be used to 
represent that program is loaded using the resource handling functions of 
Presentation Manager. 

The Icon loaded appears in the displayed representation of the Switch 
List. 

Icon Handle When an Icon is loaded using the WINLoadlcon function, 
the function returns a handle that can be used to refer to that Icon. 

The Icon Handle is stored as part of the Switch List entry for a program in 
order that the visual switch list program can display it. 

Installed Program List This is a data structure maintained by the Shell 
API which contains the description of all “Programs” that the Shell can 
recognize as programs. 

The information stored for each program includes the name of the “Exe- 
cutable File” associated with the program, a readable “Program Title” for 
it, and some execution control attributes for the program - “Program 
Type”, “Program Handle”, “Visibility”, and a description of “Program 
Parameters” . 

Presentation Manager Initialization File In order to preserve system 
control information, for example, the “Installed Program List”, all of the 
information held by the Shell API is actually held on disk. The informa- 
tion is stored in a single file, the Presentation Manager Initialization File. 
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The file is a binary file, the actual format of the data stored in the file is 
not published. Facilities are provided for applications to record their own 
permanent information as part of this file. 

Program The smallest executable unit recognized by the Shell. A 
program will minimally include a Program Title (q.v.) and a reference 
to an Executable file. 

As far as the Shell API is concerned, a program exists only after an entry 
for it has been added to the “Installed Program List” by means of the 
WSHAddProgram function. 

Program Groups These are provided to allow the collection of an arbi- 
trary set of programs into a unit that can be acted upon as a single entity. 

The relationship of program groups to programs is similar to the relation- 
ship of subdirectories to files as given in the MS OS/2 file system. It can 
be useful to think of the program group hierachy in the same way as you 
would think of the file system tree structure. Where the analogy breaks 
down, this specification will make the breakdown explicit. 

Program groups appear in the Installed Program List as if they were them- 
selves programs, and they have their own “program titles”, “program han- 
dles” and “visibility” attribute but none of the other attributes apply to 
groups. A program group can appear within another program group, i.e. 
the group structure allows nesting, but recursive group definitions are not 
permitted. 

There are several reserved handles which refer to a reserved program 
group, the complete list of programs, and two groups that are concerned 
with system configuration and start up parameters. These handles always 
exist and cannot be destroyed. They are the “Root-Group”, “Master- 
List”, the “Auto- Load-Group”, and the “Save-Group”. At Program instal- 
lation, a group handle must be specified and the program is added to the 
specified group and automatically inserted into the Master-List. 

The same entry may appear multiple times within one group. This will 
have the effect of starting the same program multiple times if the option 
to start the whole group is selected. Note: the file system does not behave 
in this way, in that within any one subdirectory you cannot have duplicate 
filenames, where a filename would correspond to the handle for a program. 
Master-List This is similar to a program group, and can be read using a 
reserved handle, but there are several differences with respect to a “nor- 
mal” program group. The Master-List can be thought of as a copy of the 
Installed Program List, except that its contents are available to a pro- 
gram. The Installed Program List is NOT made available. 
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All programs in the Installed Program List are automatically included in 
the Master-List, and cannot be removed unless the program definition is 
removed from the Installed Program List. 

The Master-List is provided to “anchor” program entries so that the 
WSHQueryProgramTitles function can be used to find all the defined 
(meaning installed) programs. 

There are NO group handles within the Master-List. All the entries are 
program handles. Further, there are no duplicate handles within the 
Master-List although duplicate titles may appear. 

The value of the reserved handle will change if the format of group and 
program handles is changed, however it will always be the value of the tar- 
get data type with all bits set to one. With the current definition of a 
group handle the value is OxFFFFFFFF. The “Name” of this structure is 
“WinMASTER-LIST” . 

Program Handle This is a number, assigned at the time a “program” is 
added to the “Installed Program List”, that uniquely identifies the pro- 
gram. 

The number used is fixed from the time a program is added to the list 
until the time it is removed. The number assigned will not be used for any 
other program or “group”. The number that represents a particular pro- 
gram will not change across a system IPL. 

Most Shell API function calls that reference programs use the program 
handle to identify a program; the program handle is the only unique refer- 
ence to a program that exists. 

Program Parameters When programs are invoked using shell they can 
be supplied with run-time parameters by the Presentation Manager sys- 
tem. 

These parameter values can be fixed, or automatic interactive prompting 
for the required information can be provided. If interactive prompts are 
selected, a number of editing options are available to control the values 
supplied by the end user at run time. 

The parameter generation is driven by information supplied at the time 
the program is installed, this information is stored as part of the Installed 
Program List entry. 

Program Reference A program group is used to collect arbitrary pro- 
grams together into a single unit. The collection process has no effect on 
the program definitions involved, the group merely indicates which pro- 
grams it contains. 
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The “Program Reference” is, therefore, just a pointer which links a group 
to each of the programs defined in that group. 

Program Title A readable name, usually in the end users natural 
language, which can be displayed to the end user. 

The title allows the user to recognize programs more easily than using an 
executable file name, and allows tailoring to national languages to be 
simplified. 

Program titles need not be unique; it is possibly, even likely, that several 
entries in the “Installed Program List” will have the same title, with the 
restriction that you cannot have duplicate titles within the same program 
group. 

Program Titles are not allowed to be null. If a null title is passed when a 
program is added to the system the system will generate a title from the 
name of the executable file associated with that program. 

Program Type Programs are divided into types based on their run-time 
attributes. They can be “Real Mode” programs, “non-Presentation 
Manager” programs that must be run in a new screen group, “non- 
Presentation Manager” programs that can run in the Presentation 
Manager screen group, or “full” Presentation Manager programs that must 
be run in the Presentation Manager screen group. These four types are 
the only distinctions that Presentation Manager makes. Note: Due to MS 
OS/2 architecture restrictions Presentation Manager may not be able to 
start programs running within the compatibility box. The user will be 
able to start them running after switching to the compatibility box and 
entering the command at the MS OS/2 prompt. 

Root Group This is a predefined program group, with a reserved group 
handle. By default, all programs in the Installed Program List are 
included in this group, unless the WSHAddProgram function specifies a 
non-zero group handle when the program is added to the Installed Pro- 
gram List. 

This group is normally the first list that the user will see when the Start- 
A-Program function is invoked. This initial view however can be changed 
by the user when he shuts the system down. In that case he will be 
presented with the same view as when the system closed. 

The value of the reserved handle may change if the format of group and 
program handles is changed, however it will always be the value of the tar- 
get data type with all bits set to zero. With the current definition of a 
group handle the value is 0. 
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The root group may contain group handles as well as program handles. (It 
would normally contain group handles.) 

The “Name” of the root group is “WinROOT-GROUP” . 

Save-Group This is a predefined program group, with a reserved group 
handle. This group will be automatically created by Presentation 
Manager when the “Save Configuration” option is selected from the File 
Cabinet. This group will be automatically started by Presentation 
Manager when the system initializes. 

The name of this group is “WinSAVE- GROUP”. 

This group is NOT for general use, and as a result has some restrictions. 

• It will only contain Program-Handles (no groups). 

• Duplicate titles will be permitted (so that the same visual appear- 
ance can be recreated). 

Selectability A Switch List entry may be selectable or non-selectable. If 
a running program has its entry in the switch list marked as non-selectable 
then it will not be possible to reach that program using the “jump applica- 
tion” “hot key” . 

An entry that is marked non-selectable can still be made active by directly 
switching to it using the WSHSwitchToProgram function, by directly 
selecting on a window of that application if it is a Presentation Manager 
application, or by bringing the Switch List to the foreground and selecting 
the entry for that application. 

Switch List This is a data structure, maintained by the API, that con- 
tains information about all of the programs that are currently executing. 
Each executing copy of a program is given an entry in the list, The entry 
contains a “Program Title” for the executing program (often the same 
name as the Installed Program List), plus some control information - 
Window Handle, if it is a program in the Presentation Manager screen 
group, Screen Group Id, if it is in a non-Presentation Manager screen 
group, Process Id for the process within which the program is running, 
Visibility and Selectability. 

Switch List Handle This is a number, assigned at the time a “program” 
is added to the “Switch List”, that uniquely identifies the executing copy 
of the program. 

The number used is fixed from the- time a program is added to the list 
until the time it is removed. The number assigned will not be used for any 
other program. 
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Most Shell API function calls that reference executing programs use the 
program handle to identify a program. 

Visibility Both the Installed Program List and Switch List have the idea 
of a visible entry. When defined, this attribute determines if the 
appropriate entry (Switch List or Installed Program List) is displayed on 
the screen. It has no other effect. In particular it says nothing about the 
visibility of whatever windows may belong to the application. 

By marking an entry as not- visible no entry will appear on the screen, 
and therefore no direct selection will be possible. Note however that it 
will still be possible to select the item by jumping to it using the jump 
application key (for Switch List entries) or by using the start program API 
calls for entries in the Installed Program List. 

The visibility attribute is returned as part of the information provided 
when the entry is read using WSHQueryProgramTitles or 
WSHQuery Definition. 

3.2.2 List of functions provided by the Shell API 

3. 2. 2.1 Program Use 

These functions allow an application to obtain the names of all defined 
programs and program groups. 

WSHQueryP rogr amHand 1 e 
WSHQueryProgramTitles 
WSHQueryP rogr amType 
WSHQueryP rogr amU s e 
WSHStartProgram 



3. 2. 2. 2 Adding a Program. 

The following functions are used to maintain the list of programs and pro- 
gram groups that are available to be started. 

The first group of functions maintain the information held for a single pro- 
gram, the smallest “executable” unit known to the Shell. 

WSHQueryP r o gr amHand 1 e 
W SHQuer yP?- o gr amType 
WSHQueryProgramTitles 

The following group of functions are used to support the collection of pro- 
grams into related groups. The list of programs within a group can be 
read using a single WSHQueryProgramTitles function. 
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W SHAddP r o gr am 
WSHAddToGr oup 
WSHCreateGroup 



3. 2. 2. 3 Switching Programs. 

The following functions are used to maintain the list of currently started 
programs, to make one of those programs the “foreground” program, 
either via direct selection or through hot-key processing, and to stop an 
executing program. 

WSHAddSwitchEntry 

WSHChangeSwitchEntry 

WSHQuerySwitchEntry 

WSHQuery S witchHand 1 e 

WinQueryTaskTit 1 e 

WinQueryTaskSizePos 

WSHQuerySwitchList 

WSHRemoveSwitchEntry 

WSHSwitchToProgram 



3. 2. 2.4 Clipboard 

The basic Clipboard functions are provided by a window management API 
and do not concern the shell. The visual clipboard (CLIPBRD.EXE in 
MS-Windows) does not need an API and is not included in this section. A 
visual clipboard will be included with the Presentation Manager product. 



3. 2. 2. 5 Control Panel 

The control panel (CONTROL.EXE) provided with MS-Windows is no 
more than a limited editor of the initialization file WIN.INI. The Presen- 
tation Manager control panel would be used to control similar settings for 
the Presentation Manager environment but would include additional func- 
tion. The Control Panel API allows a program to read/write default con- 
trol settings for the system and are listed below. 

WinQueryProfilelnt 

WinQueryProf ileString 

WinWriteProfileString 

WSHQueryProfileSize 

WSHQueryProfileData 

WSHWriteProfileData 
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3. 2. 2. 6 PrtPlot 

This section is a separate consideration. 



3.2.3 Using the API for application programmers 

This section details how the Shell API calls are used to execute various 
tasks. This is not an exhaustive list, but does give some guidelines to 
using the Shell API calls. 



3. 2. 3.1 Executing Programs 



S.2.S.1.1 Starting Presentation Manager programs 
Using the Start- A-Progr am function 

When your program has been defined in the Installed Program List, a user 
of the Start-A-Program function may select your program from the 
displayed list of programs. The program is then started in the Presenta- 
tion Manager screen group as a Presentation Manager program. 

When started in this way, the new program does not immediately appear 
in the Switch List. See the section, “Using the Switcher”, for information 
on creating the Switch List entry for your program. 

Using the DOSStartSession function 

Any application in the system can use the DOSStartSession function to 
cause a program in the Installed Program List to be started. 

The results in this case are identical to those of selecting the program 
using the Start-A-Program function. 

Using the DOSExecPgm function 

Programs started using the DOSExecPgm function will be started in the 
screen group of the program issuing the function. Thus if a Presentation 
Manager program uses DOSExecPgm then the target program will be 
started in the Presentation Manager screen group and will have access to 
the Presentation Manager functions. A program started from another 
screen group will not be able to use Presentation Manager functions since 
it will not be running in the Presentation Manager screen group. 

No switch list entry is provided for programs started in this way. Seethe 
section, “Using the Switcher”, for information on creating the Switch List 
entry for your program. 
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3. 2. 8. 1.2 Starting non-Presentation Manager programs 

These are programs which must run in a separate screen group, or have 
not been written to the Presentation Manager API. 

Using the Start-A-Program function 

When your program has been defined in the Installed Program List, a user 
of the Start-A-Program function may select your program from the 
displayed list of programs. The program is started in a new screen group. 

When started in this way, the new program is given a Switch List entry 
which is both visible and selectable. The long name of this entry is the 
program title as defined in the Installed Program List. See the section, 
“Using the Switcher”, for information on changing the Switch List entry 
for your program. 

Using the DOSStartSession function 

Any application in the system can use the DOSStartSession function to 
cause a program defined using the Add-A-Program function to be started. 

The results in this case are identical to those of selecting the program 
using the Start-A-Program function. 

The program will be started in a new screen group. 

A switch list entry is created for these programs. The entry is both visible 
and selectable, and will have a title equal to the Program Title supplied on 
the DOSStartSession call. If no Program Title is supplied then the name 
of the .EXE file is used, without any qualifying path information. 

Using the DOSExecPgm function 

Programs started using the DOSExecPgm function will be started in the 
screen group of the program issuing the function. Thus if a Presentation 
Manager program uses DOSExecPgm then the target program will be 
started in the Presentation Manager screen group and will have access to 
the Presentation Manager functions. A program started from another 
screen group will not be able to use Presentation Manager functions since 
it will not be running in the Presentation Manager screen group. 

No switch list entry is provided for programs started in this way. See the 
section, “Using the Switcher”, for information on creating the Switch List 
entry for your program. 
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3. 2. 3. 2 Creating or changing the switch list entry 

Presentation Manager programs 

• For Presentation Manager programs started by the Start- A- 
Program function, by the DOSStartSession function. 

After creating a main window, it is the application program’s 
responsibility to create a switch list entry using the 
WSHAddSwitchEntry function. The entry placed in the switch list 
can be given a default title which will be the same as the name of 
the program in the Installed Program List. 

• For programs started by means of the DOSExecPgm function, the 
above options are still available, except that the default name 
option of the WSHAddSwitchEntry function cannot be used. 

Once a switch list entry is established, it is possible to change the details 
of the entry at any time using the WSHChangeSwitchEntry function. 

As an example, this might be done by an “Editor” program in order to 
have the switch list entry show the name of the file being edited. 

Non-Presentation Manager programs. 

• For non-Presentation Manager programs started by the Start-A- 
Program function, by the DOSStartSession function. 

A switch list entry is created automatically for these programs. 

The entry will have the title of the program as defined in the . 
Installed Program List or Application Information File. This 
switch list entry will be both visible and selectable. 

Since a switch list entry is created automatically for these pro- 
grams, they may not use the WSHAddSwitchEntry function, nei- 
ther may WSHRemoveSwitchEntry be used. The switch list entry 
will be automatically deleted when the screen group terminates. 
WSHChangeSwitchEntry may be used. 

• For non-Presentation Manager programs started by means of the 
DOSStartSession function, a switch list entry is created automati- 
cally. The entry will have a long name of the program title as 
passed in the DOSStartSession request. If no title is passed, then 
the name of the program .EXE file is used. This switch list entry 
will be both visible and selectable. 

• For programs started by means of the DOSExecPgm function, no 
switch list entry is needed. This is because these programs are 
started in the same screen group as the caller, which will already 
have a switch list entry. A non-Presentation Manager screen group 
may have only one entry in the switch list. 
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Once a switch list entry is established, it is possible to change the details 
of the entry at any time using the WSHChangeSwitchEntry function. 

As an example, this might be done by an “Editor” program in order to 
have the switch list entry show the name of the file being edited. 



3. 2. 3. 3 Installation of Presentation Manager 

When Presentation Manager is installed on top of an existing MS OS/2 
system, data from existing installed programs will be extracted and copied 
across to the Presentation Manager format. Thus the user will not have to 
reinstall all his programs. 



S. 2. 3.3.1 Building the input for WSHAddProgram 

The control block structures required as input for the WSHAddProgram 
function are typically complex, they include a description of the programs 
execution environment and a descriptive name to aid the end user and 
optionally a description of the parameters required by the program to 
allow Presentation Manager to prompt the user for the required parame- 
ters at execution time. 

To simplify the task of an application programmer who is using the 
WSHAddProgram function, a function is provided to produce a valid con- 
trol block for use as input to WSHAddProgram. This function is 
WSHQueryDefinition. 

Using WSHLoadAIF 

This function will read a named AIF format file, and construct the 
corresponding control blocks from the information in the file. During the 
reading process, the files are checked for correctness, any errors in the files 
result in an error code and the control block structure is not created. 

This control block can be passed to the WSHAddProgram function 
directly, or can be modified before use. 

Using WSHQueryDefinition 

This function will reconstruct the control block structure that was used to 
add an existing Installed Program List entry to the Initialization File. 

As before, the output of this function can be used directly as input to the 
WSHAddProgram function. Notice, however, that this will result in a 
duplicate named entry in the Initialization File. While this is permitted, it 
may be confusing to the end user of the system. 



107 




Windows Presentation Manager Reference 



3. 2. 3.4 Clipboard functions 

The clipboard API is a development of the MS-Windows Clipboard API. 
The shell visual clipboard has no other API needs. For information on 
how the visual clipboard is used refer to the section, “Clipboard Viewer”. 
For information on the Clipboard API refer to “Clipboard Functions”. 



3. 2. 3. 5 Switching to another application 



3. 2. 3. 6 Using the API File Selection function 



3. 2.3. 7 File System functions. 

Presentation Manager sits on top of MS OS/2 kernel and uses the file sys- 
tem provided by DOS. All of the file system functions available under MS 
OS/2 kernel are still available under Presentation Manager. 

3.2.4 Detailed Description of Shell API Functions 

Note: In the following sections the API call definition is given in C format. 
To use the Shell API from assembler convert the C format call to assem- 
bler following the example below. The following two definitions are identi- 
cal. 

In C format: 

WSHExampleCal 1 ( (HANDLE) Handle, (char far *) Progname, 

(int) Strlength ) 

HANDLE Handle /* Program handle */) 

char ProgName[] /* (returned) Name of program */ 

int Strlength /* Length of program name buffer */ 

In ASSEMBLER format: 

EXTRN WSHExampleCal 1: FAR 

PUSH WORD Handle ; Example handle 

PUSH@ ASCIIZ ProgName ; (returned) ASCIIZ string 

PUSH WORD Strlength ; Maximum length of string 

CALL WSHExampleCal 1 

On return AX contains the return code (non-0 for an ERROR) 
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3.2.5 Program Use API 

short WSHQueryProgramHandle ( (char far *)ProgName, 

(HANDLE far *) &ProgHandle, (short) ProgCount) 
char ProgName[] /* Program names */ 

HANDLE far * ProgHandle[] /* Array of program handles */ 

short ProgCount /* Maximum count of handles */ 



Purpose Given the name of an executable file, this function will 

return the program handles using that executable file. This 
will allow the system to determine where a particular execut- 
able file is being used. 

Where: ProgName is the name of the executable file. If it is a fully 

qualified name it must match exactly with the stored name. 

If it is an unqualified executable name (no path) then a 
match will occur on every instance of a executable file of that 
name. 

ProgHandle is an array of handles. The user controls how 
many handles he wants to see by the ProgCount parame- 
ter. 

ProgCount is the dimension of the array, and thus the 
maximum number of handles that can be returned to the 
user. 

Returns: 

Count =0 No Handles matched OR Error 
(use WinGetLastError) 

<> 0 The count of handles in the array 

• No program found with given name 

• Invalid path statement 

Remarks 

long WSHQueryProgramType ( (char far *)ProgramName) 

char ProgramName [] /* Name of program being queried */ 



Purpose. 

Get the program type for a specified executable file. The 
valid types are: 

— Presentation Manager 

— Vio-windowed 

— Real 
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- — Non-Presentation Manager 
— Program- Group 
— Unknown 

Where: ProgramName is the qualified or unqualified name of a 

DOS executable file. 

Returns: 

ProgramType =0 No name matched OR Error 

<> 0 The first matching program handle 

Remarks 

If more than one program exists that matches the input pro- 
gram name, then the type of the first program found will be 
returned. It is expected that programs will always be used in 
the same environment (e.g. Presentation Manager, OR non- 
Presentation Manager but not both). 

int WSHQueryProgramTitles ( (HANDLE) GroupHandle , (GISPTR) Buffer, 
(int) BufferLen) 

HANDLE GroupHandle /* Handle of group to read */ 

GISSTRUCT Buffer /* (returned) Data Buffer */ 

int BufferLen /* Length of buffer in bytes */ 



Purpose Used to obtain information about programs and program 
groups defined as “startable” to the Shell. Information 
about all programs in a group is returned in a single opera- 
tion. The information returned is an array of entries, one for 
each program in the group. 

Where: GroupHandle is the handle of the group for which informa- 

tion is required, as returned in a previous WSHQueryPro- 
gramTitles request. The group handle may be one of the 
reserved group handles. If GroupHandle is WinROOT- 
GROUP, then information for the root group is returned. If 
GroupHandle is WinM ASTER- GROUP, then information for 
all installed programs is returned up to the size of the buffer 
provided. 

Buffer is an area of storage into which Group Information 
Structure data structure will be placed. The format of the 
Group Information Structure is given below. 

BufferLen is the maximum usable space in the buffer. 

Definition 

typedef struct gis { 

short TotalNumber; 
short ArrayCount; 

struct ProgramEntry ProgramArray [ArrayCount] ; 
> GISSTRUCT * GISPTR; 
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Where 

TotalNumber is the total count of entries in the selected 
group. 

ArrayCount is the number of entries for which there was 
room in the buffer. 

ProgramArray is an array of structures, one array element 
for each program entry within the group. The format of the 
structure is given below. 

Definition 

typedef struct ProgramEntry { 

HANDLE ProgramHandle; 

PROGTYPE ProgramType; 

/* Program/Group Handle Flag */ 
char InvisibleFlag; 

/* zero if ENTRY is visible on screen, 

non-zero if hidden */ 
char IconFileName [Smaxpathl . +1] ; 

char ProgramTitle [60+1] ; 

> PROGRAMENTRY * PROGR AMENTR YP TR ; 

Where 

ProgramHandle is the program/group handle. 

ProgramType is PROGRAM or PROGRAMGROUP. 

In the case of PROGRAM then the information as to what 
type of program this is is included. The type can be Presen- 
tation Manager, non-Presentation Manager- Windowed, and 
non-Presentation Manager-other. 

InvisibleFlag is VISIBLE if this entry appears when this 
group is displayed by the Shell, or INVISIBLE if the entry 
is not shown in the visible list. It does NOT refer to the visi- 
bility status of any windows belonging to this entry. 

IconFileName is a far pointer to an ASCIIZ filename string 
which is where the icon definition for this entry can be 
found. The pointer may be NULL in which case no icon is 
defined. 

Program Title is a character array containing the program 
title for this entry. The maximum length is 60. No leading 
or trailing blanks are preserved by the Shell API. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
• Invalid handle. 
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• Insufficient space to contain Group Information Struc- 
ture 

• Invalid Group Information Structure buffer size 

Remarks 

This function can be used to find out the number of entries 
within a group by passing a buffer of length 2 bytes. The 
function will return the total number of entries within the 
group. 

Values of BufferLen less than 2 are invalid. 

If the buffer is not large enough to contain the Group Infor- 
mation Structure an error will be reported and as many com- 
plete array entries as possible will be placed into the buffer. 

The handle specified can also be a program handle, in which 
case the buffer will only contain the entry for one program. 
Thus this call may be used to get the program title. 

The list of returned program entries may contain group han- 
dles. This allows the tree structure to be built up by the 
caller. Note though, that information from only ONE level 
of the tree structure is returned by this call. 

3.2.6 Adding a Program API 

HANDLE WSHAddProgram ( (PIBSTRUCT far *)ProgramInfo, 

(HANDLE) GroupHandle) 

PIBSTRUCT Programlnfo /* Program Information Block */ 

HANDLE GroupHandle /* Target group handle */ 



Purpose This function is used to create a new program entry in the 
Installed Program List, and to provide the initial informa- 
tion about the program. 

Where: Programlnfo is a structure containing the information 

required by Presentation Manager to control the starting 
and switching to this program. The layout of the structure 
is given below. Specifically, the title for the program is con- 
tained within the Program Information Block. 

GroupHandle is the handle, returned by WSHCreateGroup, 
of the group to which this program is to be added. 

ProgHandle is a word in which the newly generated handle 
for this program will be returned. 

Definition 

typedef struct xywinsize { 

short XPos; /* X position of Window */ 
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short 


YPos; 


/* 


Y position of Window */ 


short 


XSize; 


/* 


X extent of Window */ 


short 


XSize; 


/* 


Y extent of Window */ 


word 


WinFlag; 


/* 


MINIMISED or MAXIMISED 
or INVISIBLE or NORMAL (0) */ 


XYWINSIZE *XYWINSIZEPTR; 



Definition 



typedef struct pib 
PROGTYPE 



char 

char 

char 

char 

XYWINSIZE 

char 

short 

char 

short 

char 



P r o gr amType ; 

/* Presentation Manager, non-Presentation 
non-Presentation Manager - other , 

Group, and Visibility attribute */ 
ProgramTitle [60+1] ; 

IconFileName [&maxpathl . +1] ; 

ExecutableName [&maxpathl . +1] ; 
StartupDirectory [&maxpathl . +1] ; 
InitialPosition; 

HelpString [Shelpstrl . +1] ; 

EnvironLength; 

EnvironString [EnvironLength] ; 
ParameterLength; 

Parameterstring [1] ; 



> PIBSTRUCT *P I BSTRUCTPTR ; 



M; 



Where 



ProgramType defines the type and visibility of this pro- 
gram. If this is a PROGRAM then the type can also be 
Presentation Manager, non-Presentation Manager- 
Windowed, and non-Presentation Manager-other. If this is a 
PROGRAMGROUP, then the type of program has no mean- 
ing. The Visibility attribute defines whether this entry is 
visible in the Start-A-Program list. 

ProgramTitle is the title for this program. No leading or 
trailing blanks are preserved by the Shell API. 

IconFileName defines the icon file associated with this pro- 
gram. 

ExecutableFileName defines the executable file that will 
be run when this program is started. 

StartupDirectory defines the subdirectory that will be the 
current drive and directory when the program starts run- 
ning. 

InitialPosition is the suggested position and size to be used 
on the first WINCreateWindow call. If all values are 0, then 
the Shell will provide an initial size and position. 

HelpString is a short informative piece of help information 
for this program. This text will be displayed whenever gen- 
eral help is requested for this program. 
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EnvironLength is the length of the EnvironString. 

EnvironString defines the environment variables to be 
passed to the program when it is started. This string is in 
the format required by DOS, i.e. a set of ASCIIZ strings, the 
complete set of which is terminated by a null character. 

Parameter Length is the length of the ParameterString. 

ParameterString defines the parameter to be passed to the 
program, via its “Command Line” when it is invoked. 

Each entry in ParameterArray is a structure, as follows. 

Definition 

typedef struct parameterdescriptor { 

WORD ParameterType; 

BYTE Parameter Subtype; 

short PstringLength; 

char ParameterString [PStringLength] ; 

/* Initial path for FileSystem 
when User Selected File Name 
OR default input string */ 

> PARAMETERDESCRIPTOR *PARAMETERDESCRIPTORPTR; 

ParameterType is one of three basic types. 

• File name 

When ParameterSubtype will be one of the following 
— User selected - by definition, must exist 
— User entered - must exist 
— User entered - must not exist 
— User entered - may or may not exist 

• Free format 

• Constant 

ParameterSubtype is one of the defined filename subtypes 
if ParameterType is File-Name, otherwise it is undefined. 

PStringlength is the length of ParameterString exclud- 
ing the terminating zero. This is the length before any sub- 
stitutions have taken place. 

ParameterString is an ASCIIZ input string for the pro- 
gram. The meaning of ParameterString depends on 
ParameterType. These meanings are shown below. 

Type Meaning of ParameterString 
constant 

Input Parameter for the program. 
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user selected filename 

Initial path to use for file selection when calling 
the FileSystem. 

free format 

String from which the input parameter string is 
constructed, which may include prompting the 
user for the actual parameter. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 

• Invalid Program Information Block 

• Insufficient space to add Installed Program List entry 

• Invalid group handle 

• Title already in use in target group 

Remarks 

Program titles need not be unique, each call to this function 
will add a new definition with the same title. Note though 
that duplicate titles are NOT allowed within a group. (The 
same title can be used, but the entries must be in different 
groups.) Although the same title is permitted, it may lead to 
confusion, and is not recommended practice. The restriction 
that duplicate titles are not allowed within a group does 
ensure that if the same name appears in the listing of a 
group it is because the program has been added multiple 
times. (So that when the group is executed, the program in 
question is started multiple times.) 

The value passed in GroupHandle must be the handle of a 
defined group. The “Root” group is predefined with a handle 
of 0. The program may not be added explicitly to the 
“Master-List”. 

The initial window position and size information will be 
made available to the application by an API call. (Win- 
QueryTaskSizePos) The application may ignore the sug- 
gested defaults if it so wishes, otherwise it may use the 
defaults on the first WINCreateWindow call. 

The initial position and size fields should be 0 for a non- 
Presentation Manager application. If no defaults are 
required, then both initial X and Y extents must be set to 0. 
In this case Start-A-Program will generate a default starting 
size and position whenever the application is started. 

It is recommended that the initial size and position be 
specified as all Os, whereupon the Shell will position the win- 
dow with regard to other programs. The values in this 
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structure are device dependent and should ONLY be 
specified if the target device is known and cannot change. 

The visibility attribute is returned as part of the information 
provided in the WSHQueryProgramTitles function. An 
“invisible” group or program will not appear in the Start-A- 
Program list and so cannot be started by user selection. 

int WSHChangeProgram ( (HANDLE) ProgHandle, 

(PIBSTRUCT far *) Programlnfo) 

HANDLE ProgHandle /* Program to be changed */ 

PIBSTRUCT Programlnfo /* Changed Program Information Block */ 



Purpose To replace an existing program entry in the Installed Pro- 
gram List with a complete new definition. 

Where: ProgHandle is the handle returned by WSHAddProgram 

when the program was first added to the system. 

Programlnfo is a PIBSTRUCT data structure which is 
fully defined in the WSHAddProgram function. The format 
is: 

Definition 



typedef struct pib 
PROGTYPE 



char 

char 

char 

char 

XYWINSIZE 

char 

short 

char 

short 

char 



{ 

P r o gr amTyp e ; 

/* Presentation Manager, non-Presentation Manager 
non-Presentation Manager-other, 

Group, and Visibility attribute */ 

ProgramTitle [60+1] ; 

IconFileName [&maxpathl . +1] ; 

ExecutableName [&maxpathl . +1] ; 

StartupDirectory [&maxpathl . +1] ; 

InitialPosition; 

HelpString [&helpstrl . +1] ; 

EnvironLength ; 

EnvironString [EnvironLength] ; 

Par ameterLength ; 

Parameterstring [1] ; 



> PIBSTRUCT +PIBSTRUCTPTR; 



Where 



ProgramType defines the type and visibility of this pro- 
gram. If this is a PROGRAM then the type can also be 
Presentation Manager, non-Presentation Manager- 
Windowed, and non-Presentation Manager-other. If this is a 
PROGRAMGROUP, then the type of program has no mean- 
ing. The Visibility attribute defines whether this entry is 
visible in the Start-A-Program list. 

ProgramTitle is the title for this program. No leading or 
trailing blanks are preserved by the Shell API. 
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IconFileName defines the icon file associated with this pro- 
gram. 

ExecutableFileName defines the executable file that will 
be run when this program is started. 

StartupDirectory defines the subdirectory that will be the 
current drive and directory when the program starts run- 
ning. 

InitialPosition is the suggested position and size to be used 
on the first WINCreateWindow call. If all values are 0, then 
the Shell will provide an initial size and position. 

HelpString is a short informative piece of help information 
for this program. This text will be displayed whenever gen- 
eral help is requested for this program. 

EnvironLength is the length of the EnvironString. 

EnvironString defines the environment variables to be 
passed to the program when it is started. This string is in 
the format required by DOS, i.e. a set of ASCIIZ strings, the 
complete set of which is terminated by a null character. 

ParameterLength is the length of the ParameterString. 

ParameterString defines the parameter to be passed to the 
program, via its “Command Line” when it is invoked. 

Each entry in ParameterArray is a structure, as follows. 

Definition 

typedef struct parameter descriptor { 

WORD ParameterType; 

BYTE ParameterSubtype; 

short PstringLength; 

char ParameterString [PStringLength] ; 

/* Initial path for FileSystem 
when User Selected File Name 
OR default input string */ 

> PARAMETERDESCRIPTOR * P ARAME TERDE S CR IPTORPTR; 

ParameterType is one of three basic types. 

• File name 

When ParameterSubtype will be one of the following 
— User selected - by definition, must exist 
— User entered - must exist 
— User entered - must not exist 
— User entered - may or may not exist 
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• Free format 

• Constant 

ParameterSubtype is one of the defined filename subtypes 
if ParameterType is File-Name, otherwise it is undefined. 

PStringlength is the length of ParameterString exclud- 
ing the terminating zero. This is the length before any sub- 
stitutions have taken place. 

ParameterString is an ASCIIZ input string for the pro- 
gram. The meaning of ParameterString depends on 
ParameterType. These meanings are shown below. 



Type Meaning of ParameterString 
constant 

Input Parameter for the program, 
user selected filename 

Initial path to use for file selection when calling 
the FileSystem. 

free format 

String from which the input parameter string is 
constructed, which may include prompting the 
user for the actual parameter. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 

• Invalid program or program group handle 

• New title already exists in group 

• Invalid Program Information Block 

Remarks 

This function performs a complete replacement of the infor- 
mation stored for a program; no information is carried over 
from the existing definition. 

This function may be used to change the title or visibility of 
a program group. In this case the PROGTYPE field in the 
Program Information Block will indicate that the handle is a 
program group handle, and the Program Information Block 
will only contain the ProgramType and ProgramTitle fields. 

The group associations for the program being changed are 
not affected by this function. 

WSHQueryDefinition can be used to obtain a working copy 
of the current definition. This copy can be changed and used 
as input to this function. 
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There is no facility provided for writing the changed infor- 
mation out to a new Application Information File (AIF). 

int WSHQueryDefinition ( (HANDLE) ProgHandle, 

(PIBSTRUCTPTR) Buffer, (int) BufferLen) 

HANDLE ProgHandle /* Handle of program selected */ 

PIBSTRUCT Buffer /* Buffer for Program Information Block */ 

int BufferLen /* Length of Buffer */ 



Purpose To obtain a copy of the Program Information Block held for 
a program, or program group. The program for which infor- 
mation is required is identified by its handle. This function 
can be used to read the definition for a program group. Note 
however that a group definition ONLY consists of the 
PROGTYPE and ProgramTitle fields. 

Where: ProgHandle is the handle returned when the program was 

added to the list of programs using the WSHAddProgram 
function. 

Buffer is an area of storage into which the routine will con- 
struct the Program Information Block for this program. 

BufferLen is the maximum usable space in the buffer that is 
to be used for the Program Information Block. 

The format of a Program Information Block is shown below. 
For descriptions of the field contents within a Program Infor- 
mation Block. 

Definition 



typedef struct pib 
PROGTYPE 



char 

char 

char 

char 

XYWINSIZE 

char 

short 

char 

short 

char 



{ 

P r o gr amType ; 

/* Presentation Manager, non-Presentation R 
non-Presentation Manager - other , 

Group, and Visibility attribute */ 
ProgramTitle [60+1] ; 

IconFileName [&maxpathl . +1] ; 

ExecutableName [&maxpathl . +1] ; 
StartupDirectory [&maxpathl . +1] ; 
InitialPosition; 

HelpString [&helpstrl . +1] ; 

EnvironLength; 

EnvironString [EnvironLength] ; 

Par ameterLength ; 

Parameterstring [1] ; 



> PIBSTRUCT +PIBSTRUCTPTR; 



Where 



Program Type defines the type and visibility of this pro- 
gram. If this is a PROGRAM then the type can also be 
Presentation Manager, non-Presentation Manager- 
Windowed, and non-Presentation Manager-other. If this is a 
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PROGRAMGROUP, then the type of program has no mean- 
ing. The Visibility attribute defines whether this entry is 
visible in the Start-A-Program list. 

ProgramTitle is the title for this program. No leading or 
trailing blanks are preserved by the Shell API. 

IconFileName defines the icon file associated with this pro- 
gram. 

ExecutableFileName defines the executable file that will 
be run when this program is started. 

StartupDirectory defines the subdirectory that will be the 
current drive and directory when the program starts run- 
ning. 

InitialPosition is the suggested position and size to be used 
on the first WINCreateWindow call. If all values are 0, then 
the Shell will provide an initial size and position. 

HelpString is a short informative piece of help information 
for this program. This text will be displayed whenever gen- 
eral help is requested for this program. 

EnvironLength is the length of the EnvironString. 

EnvironString defines the environment variables to be 
passed to the program when it is started. This string is in 
the format required by DOS, i.e. a set of ASCIIZ strings, the 
complete set of which is terminated by a null character. 

ParameterLength is the length of the ParameterString. 

ParameterString defines the parameter to be passed to the 
program, via its “Command Line” when it is invoked. 

Each entry in ParameterArray is a structure, as follows. 

Definition 

typedef struct parameterdescriptor { 

WORD ParameterType; 

BYTE ParameterSubtype; 

short PstringLength; 

char ParameterString [PStringLength] ; 

/* Initial path for FileSystem 
when User Selected File Name 
OR default input string */ 

> PARAMETERDESCRIPTOR *PARAMETERDESCRIPTORPTR; 

ParameterType is one of three basic types. 

• File name 

When ParameterSubtype will be one of the following 
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— User selected - by definition, must exist 
— User entered - must exist 
— User entered - must not exist 
— User entered - may or may not exist 

• Free format 

• Constant 

ParameterSubtype is one of the defined filename subtypes 
if ParameterType is File-Name, otherwise it is undefined. 

PStringlength is the length of ParameterString exclud- 
ing the terminating zero. This is the length before any sub- 
stitutions have taken place. 

ParameterString is an ASCIIZ input string for the pro- 
gram. The meaning of ParameterString depends on 
ParameterType. These meanings are shown below. 



Type Meaning of ParameterString 
constant 

Input Parameter for the program, 
user selected filename 

Initial path to use for file selection when calling 
the FileSystem. 

free format 

String from which the input parameter string is 
constructed, which may include prompting the 
user for the actual parameter. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 

• Invalid Program Handle 

• Invalid Program Information Block buffer size 

• Insufficient space to contain Program Information Block 

Remarks 

If the buffer is not large enough to contain the Program 
Information Block an error will be reported, and the space 
that would have been required for the Program Information 
Block (in bytes) is placed in the first word of the buffer pro- 
vided. 

If the buffer is large enough the first word will be set to the 
total number of bytes used. 
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The minimum possible size for this buffer is 2 bytes, in which 
case only the numeric result field will be provided, thus indi- 
cating the actual space required for successful completion. 

If the handle is a program handle, as opposed to a group 
handle, the resulting information is in a format suitable for 
input to the WSHAddProgram and WSHChangeProgram 
functions. 

If the handle is a program group handle, then the structure 
only contains the PROGTYPE and ProgramTitle fields. 

int WSHRemoveProgram ( (HANDLE) ProgHandle) 

HANDLE ProgHandle /* Handle of Program to Remove */ 



Purpose To erase the definition of a program from the Installed Pro- 
gram List. All references to the program being removed, 
from all groups, are also removed. 

Where: ProgHandle is the handle returned for the program when it 

was added to the list by the WSHAddProgram function. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
• Invalid Program Handle 

Remarks 

You cannot use this routine to remove a group definition. 

To remove a group definition use WSHDestroyGroup. 

int WSHAddToGroup ( (HANDLE) GroupHandle, (HANDLE) ProgHandle) 
HANDLE GroupHandle /* Group handle */ 

HANDLE ProgHandle /* Program Handle */ 



Purpose To add the definition of a program or program group to an 
existing program group. 

Where: GroupHandle is a word which contains the group handle to 

which the program will be added. 

ProgHandle is the handle of the program or program group 
to be added. 

Returns: 



IF ERROR ( AX not = 0 ) 
AX = Error Code 
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• Invalid target group handle 

• Invalid source program or program group handle 

• Insufficient space to add Installed Program List entry 

• Circular reference not allowed 

• Duplicate title 

Remarks 

The target group must already exist. 



HANDLE 


WSHCreateGroup ( 


(char 


far *) GroupTitle, 




(char) GroupVis, 


(HANDLE) TargetGroupH, 




(char far *) GroupHelp) 


char 


GroupTitle [] 


/* 


Name of new group */ 


char 


GroupVis 


/* 


Visibility Option */ 


HANDLE 


TargetGroupH 


/* 


Target group handle */ 


char 


GroupHelp [] 


/* 


Help for group */ 



Purpose To add the definition of a new group of programs to the pro- 
gram list. When the group is created, it will not contain any 
program references, the WSHAddToGroup function must be 
used to place program references into a group. 

Where: GroupTitle is an ASCIIZ string which contains the readable 

text name of the group being defined. If the title is longer 
than 60 characters, then the title will be truncated. 

The title must contain valid ASCII characters; note that "\" 
is not permitted, and the string must be non-null (at least 
one non-blank character). Leading and trailing blanks are 
removed by the API before further validating the title. 

GroupVis controls the visibility attribute for the group 
entry. 

TargetGroupH is the group into which this group is to be 
placed. In order to have the group appear in the Root group 
specify a handle of 0. 

GroupHelp is a short piece of help information for this pro- 
gram group. It is optional (i.e. the pointer to the string may 
be null) but if specified the string must be non-null, with at 
least one non blank character. 

GroupHandle is a HANDLE in which the newly generated 
handle for this group will be returned. 

Returns: 



IF ERROR ( AX not = 0 ) 
AX = Error Code 
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• Invalid title 

• Invalid target group handle 

• Duplicate title 

• Insufficient space to add Installed Program List entry 

Remarks 

The visibility attribute is returned as part of the information 
provided in the WSHQueryProgramTitles function. An 
“invisible” group or program will not appear in the Start-A- 
Program list and so cannot be started by user selection. 

The Shell Start-A-Program program will honor the visibility 
attribute. 

If the group already exists, then the existing group handle 
will be returned. No new handle will be created. 

int WSHDestroyGroup ( (HANDLE) GroupHandle) 

HANDLE GroupHandle /* Handle of group to remove */ 



Purpose To remove a group definition from the Installed Program 
List, and also to remove the associations between the 
removed group and any program entries in the group. 

Where: GroupHandle is the handle of the group to be removed. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
• Invalid group handle. 

Remarks 

It is not permitted to remove either the “Root” group or 
“Master-List” . 

int WSHRemoveFromGroup ( (HANDLE) GroupHandle, (HANDLE) ProgHandle) 
HANDLE GroupHandle /* Group handle */ 

HANDLE ProgHandle /* Program Handle */ 



Purpose To remove the definition of a program from a group in the 
Installed Program List. 

Where: GroupHandle is the handle of the group from which the 

program association is to be removed. 

ProgHandle is the handle of the program for which the 
association is to be removed. 
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Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 

• Invalid group handle 

• Handle does not exist within group 

Remarks 

It is not possible to remove the association between the 
“Master-List” and a program. 

If the same program appears multiple times within a group 
(which must have been caused by multiple WSHAddToGroup 
calls) then WSHRemoveFromGroup will only remove one 
definition. WSHRemoveFromGroup will have to be called as 
many times as WSHAddToGroup was called to delete the 
program entirely from the group. 

3.2.7 Switching Programs API 

HANDLE WSHAddSwitchEntry ( (SWCNTRL far *) Control) 

SWCNTRL far * Control /* Switch list control information */ 



Purpose Add an entry to the switch list. The entry need not neces- 
sarily be made visible, but it must refer to a process that is 
currently running. 

Where: Control is a structure with the following format: 

Definition 

typedef struct swcontrol { 

char SwTitle [60+1] ; 



HANDLE 


WindowHandle; 


/* 


0 if no window */ 


HANDLE 


IconHandle; 


/* 


0 if no icon */ 


HANDLE 


ProgramHandle 


/* 


0 if not an installed proc 


WORD 


Processld; 


/* 


For this entry */ 


WORD 


Sessionld; 


/* 


For this entry */ 


BYTE 


SwitchFlagA; 






BYTE 


SwitchFlagB; 







> SWCNTRL * SWCNTRLPTR ; 

Where 

SwTitle is the ASCIIZ title for this entry. It must be a 
non-null string in order to define a valid switch list entry. 

WindowHandle is the handle of the main window belong- 
ing to this entry. (0 means that there is no window, in which 
case this is a non-Presentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 
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ProgramHandle is the program handle that was used to 
start the program resulting in this entry in the switch list. 

Only items in the switch list that have a program handle 
entry can be included in the SAVE CONFIGURATION func- 
tion as these are the only programs that the Shell knows how 
to get started. 

Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session 
id is generated by DOS when starting a new session running. 

This is a read only field and may NOT be changed by the 
user. 

SwitchFlagA defines the visibility of an entry in the Switch 
List. It is a byte with ONE of the following values: 

NOT_ VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value = 0) 

— NOT- VISIBLE means that this entry will not appear 
in the visual switch list, but can be selected by the user 
by using the Jump-Application hotkey, or, if it is a 
Presentation Manager application, making a direct selec- 
tion on one of the windows belonging to that application. 

— NOT- SELECTABLE means that this entry is not 
enabled for selection. (On a colour screen it will appear 
grayed.) 

— SWL_ NORMAL means that this entry is both visible 
and enabled for selection. (This is the default when 0 is 
given.) 

SwitchFlagB defines the response of this entry to the 
Jump- Application hotkey. It is a byte with ONE of the 
following values: 

JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DISABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be 
activated as a result of pressing the Jump-Application 
hotkey. 

— - JUMP- DISABLED means that this entry will not be 
activated as a result of pressing the Jump- Application 
hotkey. The application can still be activated by directly 
selecting the entry in the Switch List (if the entry is visi- 
ble and enabled) or, if it is a Presentation Manager appli- 
cation, by making a direct selection on one of the win- 
dows belonging to that application. 

SwHandle is the handle to the switch list entry for this pro- 
gram and should be used on subsequent switch list 
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processing calls. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = 0 implies error (use WinGetLastError call) 
AX/DX = SwHandle 

• (Presentation Manager) Main Window already in switch 
list 

• (Non-Presentation Manager) Screen group already in 
switch list 

• Invalid window handle 

• Not a main window handle 

• Invalid parameter block 

• Invalid icon handle 

• Invalid name 

• Switch list full 

• Invalid Process Id 

Remarks 

If a null string is passed for the entry name Presentation 
Manager will use the name under which the application was 
started. This ONLY applies to Presentation Manager appli- 
cations, and only to the first WSHAddSwitchEntry for that 
application. Otherwise a null name (i.e. a name consisting of 
only the terminating zero) is invalid. 

Leading and trailing blanks will be removed from the pro- 
gram title. This ensures a consistent user view. If the pro- 
gram title is longer than 60 bytes it will be truncated. 

There is an implementation maximum of the number of 
Switch List entries. However the maximum number will be 
several hundred programs and there should be no reason to 
reach the limit. Before the limit is reached other machine 
limitations will have been encountered. 

The program handle will be passed across to the Switch List 
and will mean that the program started in this manner can 
be stored during shutdown of the machine and restored later 
by the Shell restore configuration function. 

If a program has been registered with the WSHSwitchPro- 
gramRegister call then this API will send a message to the 
window defined by the WSHSwitchProgramRegister. This 
message has the following format: 

SH_SWITCHLI ST 
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lParaml: DWORD idAddEntry 

lParam2 : HANDLE Switch Handle 

Returns : OL 



Description 

This message is used by all the Task Manager rou- 
tines to inform the visual shell that a new entry 
has been made to the Switch List. 

This message is always queued. 

The handle is the new switch list handle. 

int WSHChangeSwitchEntry ( (HANDLE) SwHandle, (SWCNTRL far *)SwControl) 
HANDLE SwHandle /* Switch List Handle */ 

SWCNTRL far * SwControl /* Switch list control block */ 



Purpose Alter the attributes and/or name of an entry in the switch 
list. 

Where: SwHandle is the switch list entry handle whose information 

is to be changed. 

SwControl is the same structure defined for 
WSHAddSwitchEntry and has the following form. 

Definition 

typedef struct swcontrol { 



char 

HANDLE 


SwTitle [60+1] ; 
WindowHandle; 


/* 


0 if no window */ 


HANDLE 


IconHandle; 


/* 


0 if no icon */ 


HANDLE 


P r o gr amHand 1 e 


/* 


0 if not an installed program 


WORD 


Processld; 


/* 


For this entry */ 


WORD 


Sessionld; 


/* 


For this entry */ 


BYTE 

BYTE 


SwitchF 1 agA; 
SwitchFlagB; 



> SWCNTRL * SWCNTRLPTR ; 

Where 

SwTitle is the ASCIIZ title for this entry. It must be a 
non-null string in order to define a valid switch list entry. 

WindowHandle is the handle of the main window belong- 
ing to this entry. (0 means that there is no window, in which 
case this is a non-rresentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 

ProgramHandle is the program handle that was used to 
start the program resulting in this entry in the switch list. 
Only items in the switch list that have a program handle 
entry can be included in the SAVE CONFIGURATION func- 
tion as these are the only programs that the Shell knows how 
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to get started. 

Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session 
id is generated by DOS when starting a new session running. 

This is a read only field and may NOT be changed by the 
user. 

SwitchFlagA defines the visibility of an entry in the Switch 
List. It is a byte with ONE of the following values: 

NOT_VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value == 0) 

— NOT- VISIBLE means that this entry will not appear 
in the visual switch list, but can be selected by the user 
by using the Jump-Application hotkey, or, if it is a 
Presentation Manager application, making a direct selec- 
tion on one of the windows belonging to that application. 

— NOT- SELECTABLE means that this entry is not 
enabled for selection. (On a colour screen it will appear 
grayed.) 

— SWL_ NORMAL means that this entry is both visible 
and enabled for selection. (This is the default when 0 is 
given.) 

SwitchFlagB defines the response of this entry to the 
Jump- Application hotkey. It is a byte with ONE of the 
following values: 

JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DI SABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be 

activated as a result of pressing the Jump- Application 
hotkey. 

— JUMP- DISABLED means that this entry will not be 
activated as a result of pressing the Jump-Application 
hotkey. The application can still be activated by directly 
selecting the entry in the Switch List (if the entry is visi- 
ble and enabled) or, if it is a Presentation Manager appli- 
cation, by making a direct selection on one of the win- 
dows belonging to that application. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
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• Invalid Handle 

• Invalid Icon Handle 

• Invalid Program Title (it cannot be zero length) 

• Invalid SWCNTRL block 

• Invalid Process Id 

Remarks 

The maximum length of a program title in the switch list is 
60. Any entry longer than this will have the title truncated 
with no warning. 

If a program has been registered with the WSHSwitchPro- 
gramRegister call, then this API will send a message to the 
window defined by the WSHSwitchProgramRegister. This 
message has the following format: 

SH_S WI TCHL 1ST 

lParaml: DWORD idChangeEntry 

lParam2 : HANDLE Switch Handle 

Returns : OL 



Description 

This message is used by all the Task Manager rou- 
tines to inform the visual shell that an entry in the 
Switch List, has been changed. 

This message is always queued. 

The handle is the changed switch list handle. 

int WSHQuerySwitchEntry ( (HANDLE) SwHandle, (SWCNTRLPTR) Buffer) 
HANDLE SwHandle /* Switch List Handle */ 

SWCNTRL far * Buffer /* Buffer for definition */ 



Purpose To obtain a copy of the Switch List Control block for a 

specific application. The application for which information 
is required is identified by its handle. 

Where: SwHandle is the handle returned when the program was 

added to the switch list using the WSHAddSwitchEntry 
function. 

Buffer is an area of storage into which the routine will con- 
struct the switch list entry for this program. 

Returns: 



IF ERROR ( AX not = 0 ) 
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AX = Error Code 

• No entry corresponding to handle 

Remarks 

If SwHandle cannot be found, for whatever reason, then an 
error is returned. 

This call is available to non-Presentation Manager applica- 
tions. 

HANDLE WSHQuerySwitchHandle ( (HANDLE) WHandle, (WORD) ProcessID) 
HANDLE WHandle /* Window Handle */ 

WORD ProcessID /* Process ID */ 



Purpose Find the switch list handle belonging to a specific process or 
window. This is used by those applications that know what 
the window handle is (via some other means) and want to 
alter or query the attributes of the entry for this window in 
the switch list. 

Where: WHandle is a window handle for an application running in 

the Presentation Manager screen group for which the switch 
list handle is required or 0. 

ProcessID is the process id for which a switch list handle is 
required or 0. This is mutually exclusive with the first 
parameter and is designed for use by non-Presentation 
Manager applications which do not have a window handle. 

SwHandle is set to the switch list handle for this entry, if 
the entry exists (i.e. AX "= 0). If no matching entry can be 
found in the switch list then 0 is returned. 

Returns: 

IF ERROR ( AX = 0 ) 

Use WinGetLastError 

• Invalid handle 

• Invalid process id 

• Invalid parameters 

• No entry in switch list 

Remarks 

This entry could be used by a parent application after start- 
ing a child in order to change or modify the switch list entry 
for the child, or even to use' the shell facilities to kill the 
child. For example, it may well be the easiest way to prompt 
the user to confirm the death of a child process. 

If both window handle and process id are provided they must 



131 




Windows Presentation Manager Reference 



be consistent with each other. Otherwise NO handle will be 
returned. 

int WinQueryTaskTitle ( (word) ProcessID, (char far *) NameBuf fer , 
(int) Buf ferLen) 

word ProcessID /* Process ID */ 

char far * NameBuf fer /* (returned) Program name */ 

int BufferLen /* Maximum buffer length */ 



Purpose Find the title which this program has in the Switch List. 

This is used by those applications that want to know what 
string the user associates with this program. The applica- 
tion can then use the same string in its window and/or 
switch list entry. The main purpose of the call is before an 
application creates its first window, when it can insert the 
same title into the window and Switch List as appears in the 
Start-A-Program list. 

Where: ProcessID is the process id to identify the application 

whose title is required. 

NameBuffer is filled with the name of this process, if the 
program is known by the shell. 

BufferLen is the maximum length of NameBuffer. If the 
name is too long to fit into the buffer the name will be trun- 
cated. The maximum number of characters of title that can 
be copied to the buffer is BufferLen-1 as there must always 
be room for a terminating zero. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX - Error Code 

• process id is not known 

• Title truncated 

Remarks 

Use this entry to get the title associated with a program. 

If found, the name will be copied to the supplied buffer, with 
a terminating zero added. 

int WinQueryTaskSizePos ( (word) ProcessID, (XYWINSIZE far *) PositionBlock) 
word ProcessID /* Process ID */ 

XYWINSIZE PositionBlock /* (returned) Size and Position */ 



Purpose Find the size and position for the initial window. 
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Where: ProcessID is the process id to identify the application 

whose title is required. 

PositionBlock is filled with the size and position to use 
when creating the window. PositionBlock has the following 
structure: 

Definition 



typedef struct 


xywinsize { 








short 


XPos; 


/* 


X position 


of Window */ 


short 


YPos; 


/* 


Y position 


of Window */ 


short 


XSize; 


/* 


X extent of 


Window */ 


short 


XSize; 


/* 


Y extent of 


Window */ 


word 


WinFlag; 


/* 


MINIMISED or MAXIMISED 



or INVISIBLE or NORMAL (0) */ 
> XYWINSIZE *XYWINSIZEPTR; 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
• process id is not known 

Remarks 

Use this entry to get the suggested size and poistion to use 
for the first window created. The system will provide default 
values if there are no values stored for this particular pro- 
gram. (i.e. there is no program handle, because a .EXE or 
.CMD file was started.) 

If a window size and position needs to be generated by the 
shell (i.e. Switch List) the units returned will be those that 
can be used on the Presentation Manager create window API 
calls. 

The values returned will be for the frame window, not the 
client area. The size will be large enough to provide a non- 
null client area which will be no more than one quarter of 
the available windowing area. The exact algorithm to be 
used will not form part of the specification. 

short WSHQuerySwitchList ( (SWBlock far *)Buffer, (int)Length) 

SWBlock far * Buffer /* Buffer into which to copy data */ 
int Length /* Length of buffer in bytes */ 



Purpose To collect information about entries defined in the switch 
list. Information about all entries in the switch list is 
returned in a single operation, each individual entry being 
defined by a single array element. 
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Where: Buffer will be set to the Switch List Block as described 

below. 

Length is the length in bytes of the buffer. If Length=0 
then only the number of entries in the list is returned. This 
is also the case if a null address is given for Buffer. 

Definition 

typedef struct SWBlock -{ 

WORD SwNumber; /* Number in SwListArray */ 

SWENTRY SwListArray [SwNumber] ; 

> SWBLOCK * SWBLOCKPTR ; 

Where 

SwNumber is a count of the number of array entries 
returned. 

SwListArray is an array with the given number of entries 
of SWENTRY structures. 

The SWENTRY structure is shown below. 

Definition 

typedef struct swentry { 

HANDLE SwHandle; /* Switch list handle for this entr 

SWCNTRL SwControl ; ' 

> SWENTRY * SWENTRYPTR ; 

Where 

SwHandle is the Switch List handle for this entry. 

SwControl is the SWCNTRL structure as given below. 

Definition 

typedef struct swcontrol { 



char 

HANDLE 


SwTitle [60+1] ; 
WindowHandle; 


/* 


0 if no window */ 


HANDLE 


IconHandle; 


/* 


0 if no icon */ 


HANDLE 


ProgramHandle 


/* 


0 if not an installed program * 


WORD 


Processld; 


/* 


For this entry */ 


WORD 


Sessionld; 


/* 


For this entry */ 


BYTE 

BYTE 


SwitchFlagA; 
S wi tchF 1 a gB ; 



> SWCNTRL * SWCNTRLPTR ; 

Where 

SwTitle is the ASCIIZ title for this entry. It must be a 
non-null string in order to define a valid switch list entry. 

WindowHandle is the handle of the main window belong- 
ing to this entry. (0 means that there is no window, in which 
case this is a non-rresentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 
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ProgramHandle is the program handle that was used to 
start the program resulting in this entry in the switch list. 

Only items in the switch list that have a program handle 
entry can be included in the SAVE CONFIGURATION func- 
tion as these are the only programs that the Shell knows how 
to get started. 

Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session 
id is generated by DOS when starting a new session running. 

This is a read only field and may NOT be changed by the 
user. 

SwitchFlagA defines the visibility of an entry in the Switch 
List. It is a byte with ONE of the following values: 

NOT_VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value == 0) 

— NOT_ VISIBLE means that this entry will not appear 
in the visual switch list, but can be selected by the user 
by using the Jump-Application hotkey, or, if it is a 
Presentation Manager application, making a direct selec- 
tion on one of the windows belonging to that application. 

— NOT- SELECTABLE means that this entry is not 
enabled for selection. (On a colour screen it will appear 
grayed.) 

— SWL_ NORMAL means that this entry is both visible 
and enabled for selection. (This is the default when 0 is 
given.) 

SwitchFlagB defines the response of this entry to the 
Jump- Application hotkey. It is a byte with ONE of the 
following values: 

JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DI SABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be 
activated as a result of pressing the Jump- Application 
hotkey. 

— JUMP- DISABLED means that this entry will not be 
activated as a result of pressing the Jump- Application 
hotkey. The application can still be activated by directly 
selecting the entry in the Switch List (if the entry is visi- 
ble and enabled) or, if it is a Presentation Manager appli- 
cation, by making a direct selection on one of the win- 
dows belonging to that application. 
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Returns: 

IF ERROR ( AX = 0 ) 

ELSE AX = Total number of switch list entries 

Remarks 

The Switch List Block is built into the block of storage pro- 
vided by the caller. The total number of Switch List entries 
will always be returned to the caller. 

int WSHRemoveSwitchEntry ( (HANDLE) SwHandle) 

HANDLE SwHandle /* Switch list handle */ 



Purpose Remove an entry from the switch list. 

Where: SwHandle is the switch list handle of the entry to be 

removed. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 
• Entry cannot be removed 

Remarks 

Well behaved applications should call WSHAddSwitchEntry 
to include themselves in the switch list when they start to 
run and also call WSHRemoveSwitchEntry before terminat- 
ing to remove their entry from the switch list. 

In addition the window management will ensure that the 
switch list entry is removed when a window is destroyed by 
calling WSHRemoveSwitchEntry. 

Entries for non-Presentation Manager programs CANNOT 
be explicitly removed by the program. They will be removed 
by the Shell when the screen group terminates. 

int WSHSwitchToProgram ( (HANDLE) SwHandle) 

HANDLE SwHandle /* Switch list handle */ 



Purpose Make a specific program the active program. This will 

involve jumping to another window within the Presentation 
Manager screen group, and bringing that, and all related 
windows, to the “front” of the screen, or switching to 
another screen group in the case of a non-Presentation 
Manager program. In either case, the keyboard (and mouse 
for non-Presentation Manager) input will be directed to the 
new program. 
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Where: SwHandle is the switch list entry of the program which is to 

be made the foreground process. 

Returns: 

IF ERROR ( AX not = 0 ) 

AX = Error Code 

• Invalid handle 

• Requesting program is NOT the foreground process 

Remarks 

It is only possible to make an arbitrary application the fore- 
ground process if you are currently the foreground process. 

In all other cases the call is ignored. A foreground process is 
defined as being any process within the active screen group 
in the case of non-Presentation Manager applications, and 
the window with the input focus for applications running in 
the Presentation Manager screen group. 

3.2.8 Presentation Manager Initialization File 
and Control Panel API 



3.2.8. 1 Overview of control panel 

The Control Panel allows the user to tailor certain aspects of the system 
for personal preference, and to alter the system configuration. The func- 
tions provided by the control panel allow the user to: 

• Set the system clock (date and time) 

• Change the screen colors (for example, Scroll bars, title line, win- 
dow text, etc...) 

• Change the default printer 

• Change the printer configuration (meaning the port the printer is 
attached to) 

• Change the country settings (Country, time format, number 
representation, date format, and currency symbol) 

• Change the mouse buttons (swap left and right) 

• Set the double click time 

All of the above functions are interactive, and the user is allowed to try (or 
look at) the new settings before confirming the change. After the change 
is made the new settings are permanently stored. 
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Some of the information above is provided by system calls and are outside 
the scope of the Shell API. The calls detailed below allow the visual con- 
trol panel to access data that is either available in the system but not pro- 
vided in a convenient form, or not available anywhere else. 

The information is stored in PRESSERV.INI in a structured binary form. 
The API calls below access the relevant parts of this structured file. The 
basic operation done by the API calls will be to execute 
WINGetProfileString for a section of PRESSERV.INI and then extract the 
data from the binary data read from the file. Similarly the write opera- 
tions will construct a binary structure with the information passed across 
the API and write the new structure to PRESSERV.INI by calling 
WINWriteProfileString 

Listed in the section, “Presentation Manager Initialization File Func- 
tions”, are the low-level calls used to access PRESSERV.INI. 



3.2.9 Presentation Manager 

Initialization File Functions 

This section describes the functions used to read from and write to the 
Presentation Manager initialization file, PRESSERV.INI. The Presenta- 
tion Manager initialization file is a special MS OS/2 file that contains 
keyname-value pairs (within specific application sections) that represent 
runtime options for applications. 

It is a binary file and is thus NOT considered a text editable file. Any 
application wishing to use PRESSERV.INI should use the API given below 
to read and write the file. In this way users of the file can be shielded from 
the way in which the file is stored. 

There are the following functions: 

WINQueryProfilelnt 
WINQueryPro fileString 
WINWriteProfileString 
WSHQueryProfileSize 
WSHQueryPr o f i 1 eData 
WSHWriteProfileData 



int WINQueryProfilelnt ( (HANDLE ) hab , (LPSTR) IpApplicationName, 
(LPSTR) lpKeyName, (int) nDefault) 

HANDLE hab; 

LPSTR IpApplicationName; 

LPSTR lpKeyName; 

int nDefault; 
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Purpose This function retrieves the value of an integer key from the 
the Presentation Manager initialization file PRESSERV.INI. 
The function searches the Presentation Manager initializa- 
tion file for a key matching the name specified by lpKey- 
Name under the application heading specified by lpApplica- 
tionName. 

An integer entry in the Presentation Manager initialization 
file must have the following form: 

[ <Application-Name> ] 

<Key-Name> = <value> 

where value is the key’s integer value. 

Parameters 



Parameter 

Significance 

hab The value returned by the Winlnitialize function. 
IpApplicationName 

A long pointer to a character string naming the 
application. The string must be a null-terminated 
ASCII string. 

lpKeyName 

A long pointer to a character string naming a key. 

The string must be a null-terminated ASCII string. 

nDefault 

A short integer value specifying the default value 
for the given key if the key cannot be found in the 
Presentation Manager initialization file. 

Return Value 

The return value is a short integer value specifying the value 
of the given key if the key exists. Otherwise, it is equal to 
nDefault. 

The WINQueryProfilelnt function returns zero, instead of 
the default value, if the value corresponding to the specified 
keyname is not an integer. If the value corresponding to the 
keyname consists of digits followed by non-numeric charac- 
ters, the function returns the value of the digits. For exam- 
ple, if the entry ’KeyName=102abc’ is accessed, the function 
returns 102. 

int WINQueryPro fileString ( (HAB) hab, (LPSTR) IpApplicationName, 

(LPSTR) lpKeyName, (LPSTR) lpDefault, (LPSTR) IpReturnedString, 
(int) nSize) 

HAB hab; 

LPSTR IpApplicationName; 
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LPSTR lpKeyName; 

LPSTR lpDe fault; 

LPSTR IpReturnedString; 
int nSize; 



Purpose This function copies a character string from the user profile, 
PRESSERV.INI, into the buffer pointed to by IpReturned- 
String. The function searches the Presentation Manager ini- 
tialization file for a key matching the name specified by 
lpKeyName under the application heading specified by lpAp- 
plicationName. If the key is found, the corresponding string 
is copied to the buffer. If the key does not exist, the default 
character string, lpDefault, is copied. 

A string entry in the Presentation Manager initialization file 
must have the following form: 

[ <Application-Name> ] 

<Key-Name> = <string> 

where string is an ASCII string. 

If IpApplicationName is NULL, WINQueryProfileString 
enumerates all application names in PRESSERV.INI and fills 
the location pointed to by IpReturnedString with a list of 
application names (not keynames or values). Each applica- 
tion name in the list is terminated with a null character. 

The last string in the list is terminated with two null charac- 
ters. WINQueryProfileString returns the length of the list, 
up to, but not including, the final null. 

If lpKeyName is NULL, WINQueryProfileString enumerates 
all keynames associated with IpApplicationName by filling 
the location pointed to by IpReturnedString with a list of 
keynames (not values). Each keyname in the list is ter- 
minated with a null character. The last string in the list is 
terminated with two null characters. WinQueryProfileString 
returns the length of the list, up to, but not including, the 
final null. 

Parameters 



Parameter 

Significance 

hab The value returned by the Winlnitialize function. 
IpApplicationName 

A long pointer to a character string naming the 
application. The string must be a null-terminated 
ASCII string. 
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lpKeyName 

A long pointer to a character string naming a key. 

The string must be a null- terminated ASCII string. 

lpDefault 

A long pointer to the character string to be used if 
the given key does not exist. It must be a null- 
terminated ASCII string. 

IpReturnedString 

A long pointer to the buffer to receive the charac- 
ter string. 

nSize A short integer value specifying the maximum 

number of bytes to be copied to the buffer. If the 
actual string is longer, it is truncated. 

Return Value 

The return value is a short integer value specifying the 
actual number of characters copied to IpReturnedString. 

Notes WinQueryProfileString is not case-dependent, so the strings 
in IpApplicationName and lpKeyName may be in any combi- 
nation of uppercase and lowercase letters. 

BOOL WINWritePro fileString ( (HAB) hab, (LPSTR) IpApplicationName, 
(LPSTR) lpKeyName, (LPSTR) IpString) 

HAB hab; 

LPSTR IpApplicationName; 

LPSTR lpKeyName; 

LPSTR IpString; 



Purpose This function copies the character string pointed to by 

IpString into the Presentation Manager initialization file, 
PRESSERV.INI. This function searches the Presentation 
Manager initialization file for the key named by lpKeyName 
under the application heading specified by IpApplication- 
Name. If there is no match, it adds a new string entry to the 
user profile. If there is a matching key, the function replaces 
that key’s value with IpString. 

If there is no application field for IpApplicationName, this 
function creates a new application field and places an 
appropriate key-value line in that field of the Presentation 
Manager initialization file. 

A string entry in the Presentation Manager initialization file 
has the following form: 

[ <Application-Name> ] 

<Key-Name> = <string> 

where string is an ASCII string. 
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Parameters 



Parameter 

Significance 

hab The value returned by the Winlnitialize function. 
IpApplicationName 

A long pointer to a character string naming the 
application. The string must be a null-terminated 
ASCII string. 

lpKeyName 

A long pointer to a character string naming the 
desired key. The string must be a null-terminated 
ASCII string. 

lpValue A long pointer to the string to be copied to the file. 

The string must be a null-terminated ASCII string. 

Return Value 

The return value, a Boolean value, is nonzero if the function 
is successful. Otherwise, it is zero. 

Notes Applications that make changes to the PRESSERV.INI file in 
sections that are also accessed by other applications must 
send a WM_WININICHANGE message to all applications in 
the system. 

int WSHQueryProfileSize ( (HANDLE ) hab , (LPSTR) IpApplicationName, 
(LPSTR) lpKeyName, (int far *) lpValueSize) 

HANDLE hab; 

LPSTR IpApplicationName; 

LPSTR lpKeyName; 

int far * lpValueSize; 



Purpose This function returns the size of a particular keyname-value 
pair in the Presentation Manager initialization file 
PRESSERV.INI. The function searches the Presentation 
Manager initialization file for a key matching the name 
specified by lpKeyName under the application heading 
specified by IpApplicationName. The size returned includes 
any trailing zero bytes included for zero terminated strings. 

Where: hab is the anchor block handle as returned by WINInitialize. 

IpApplicationName is a pointer to an ASCIIZ string iden- 
tifying the application section within PRESSERV.INI that is 
of interest. 

lpKeyName is a pointer to an ASCIIZ string identifying the 
keyname pair for which the value length is required. 

lpValueSize is a pointer to an integer value which will be 
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set to the size of the value field. If an error occurs the con- 
tents of this variable will be unchanged. 

Returns: 

The possible error conditions are 

• Application name not found 

• Key name not found 

• Error accessing PRESSERV.INI 

Remarks 

This call is provided so that an application can find out the 
size of a value field in PRESSERV.INI, where that size is 
unknown, in order to pass the correct buffer size when calling 
WSHQueryProfileData. 



int WSHQueryProfileData ( (HANDLE) hab, (LPSTR) lpApplicationName, 
(LPSTR) lpKeyName, (LPSTR) lpBuffer , (int far *)lpnSize) 
HANDLE hab; 

LPSTR lpApplicationName; 

LPSTR lpKeyName; 

LPSTR lpBuffer; 

int far * lpnSize; 



Purpose This function returns a string of binary data from the 

Presentation Manager initialization file PRESSERV.INI. 

The function searches the Presentation Manager initializa- 
tion file for a key matching the name specified by lpKey- 
Name under the application heading specified by lpApplica- 
tionName. 

Where: hab is the anchor block handle as returned by WINInitialize. 

lpApplicationName is the application name identifying the 
section within PRESSERV.INI. 

lpKeyName is the keyname identifying the keyname- value 
pair within PRESSERV.INI. 

lpBuffer is where the data will be returned into. The 
returned string will not be zero terminated, unless the value 
string is explicitly zero terminated within PRESSERV.INI 
This is a call handling binary data. 

lpnSize is a long pointer to an integer value giving the max- 
imum size of the buffer. If the function is successful this will 
be overwritten with the number of bytes copied into the 
buffer. 

Returns If Retcode /= 0 an error occurred. (Otherwise lpnSize is the 
number of bytes copied into the buffer.) The possible return 
code values are 
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— No match on application name 
— No match on key name 
— Not enough room for data 
— Error accessing PRESSERV.INI 

Remarks 

Because of the binary nature of the data the returned data is 
not zero terminated. It is up to the application to use the 
length provided in order to process the data. 

int WSHWriteProfileData ( (HANDLE)hab, (LPSTR) IpApplicationName, 
(LPSTR) lpKeyName, (LPSTR) lpBuffer, (int)nSize) 

HANDLE hab; 

LPSTR IpApplicationName; 

LPSTR lpKeyName; 

LPSTR lpBuffer; 

int nSize; 



Purpose This function writes a string of binary data of length nSize 
to the Presentation Manager initialization file, putting the 
data into the area identified by the Application Name 
Key Name parameter pair. 

Where: hab is the anchor block handle as returned by WINInitialize. 

IpApplicationName is the application name identifying the 
section within PRESSERV.INI. 

lpKeyName is the keyname identifying the keyname-value 
pair within PRESSERV.INI. 

lpBuffer is data to be written. This string is NOT zero ter- 
minated, and the length is obtained from the following 
parameter. 

nSize is the size of the data to be written. 

Retcode is the return value. The return value is 0 if the 
function worked, otherwise is one of the error values listed 
below. 

Returns Return code values 

— Invalid application name 
— Invalid key name 
— Error accessing PRESSERV.INI 

Remarks 

Because of the binary nature of the data, the input data is 
not zero terminated. The length provided is the only way to 
identify the length of the data. 
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3.3 Shell API Structure definitions 



3.3.1 Shell API data structure reference 

This section lists all the data structures used by the Presentation Manager 
Shell API. 

Definition 

typedef struct gis { 

short TotalNumber; 
short ArrayCount; 

struct ProgramEntry ProgramArray [ArrayCount] ; 

> GISSTRUCT *GISPTR; 

Where 

TotalNumber is the total count of entries in the selected group. 

ArrayCount is the number of entries for which there was room in the 
buffer. 

ProgramArray is an array of structures, one array element for each pro- 
gram entry within the group. The format of the structure is given below. 

Definition 

typedef struct ProgramEntry { 

HANDLE ProgramHandle; 

PROGTYPE ProgramType; 

/* Program/Group Handle Flag */ 
char InvisibleFlag; 

/* zero if ENTRY is visible on screen, 

non-zero if hidden */ 
char IconFileName [&maxpathl . +1] ; 

char ProgramTitle [60+1] ; 

> PROGRAMENTRY *PROGRAMENTRYPTR; 

Where 

ProgramHandle is the program/group handle. 

ProgramType is PROGRAM or PROGRAMGROUP. In the case of 
PROGRAM then the information as to what type of program this is is 
included. The type can be Presentation Manager, non-Presentation 
Manager- Windowed, and non-Presentation Manager-other. 

InvisibleFlag is VISIBLE if this entry appears when this group is 
displayed by the Shell, or INVISIBLE if the entry is not shown in the 
visible list. It does NOT refer to the visibility status of any windows 
belonging to this entry. 

IconFileName is a far pointer to an ASCIIZ filename string which is 
where the icon definition for this entry can be found. The pointer may be 
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NULL in which case no icon is defined. 

Program Title is a character array containing the program title for this 
entry. The maximum length is 60. No leading or trailing blanks are 
preserved by the Shell API. 

Definition — ' 

typedef struct progarray { 

short TotalCount; /* Total number of entries in list */ 

short ArrayCount; /* Number of array elements */ 

HANDLE ProgramArr [ArrayCount] ; /* Program handles */ 

> PROGARRAY +PROGARRAYPTR; 

Where 

TotalCount is the total number of program or program group entries in 
the list. 

ArrayCount is the size of the array that fits into the buffer of the given 
length. 

ProgramArr is the array of program, or program group handles. 

Definition 

{ _ 

P r o gr amType ; 

/* Presentation Manager, non-Presentation Manager-Wina^ ,.ed, 
non-Presentation Manager -other. 

Group, and Visibility attribute */ 

ProgramTitle [60+1] ; 

IconF ileName [&maxpathl . +1] ; 

ExecutableName [&maxpathl . +1] ; 

StartupDirectory [&maxpathl . +1] ; 

InitialPosition; 

HelpString [&helpstrl . +1] ; 

En vironLength ; 

EnvironString [EnvironLength] ; 

ParameterLength; 

Parameterstring [1] ; 

> PIBSTRUCT +PIBSTRUCTPTR; 

Where 

ProgramType defines the type and visibility of this program. If this is a 
PROGRAM then the type can also be Presentation Manager, non- 

Presentation Manager- Windowed, and non-Presentation Manager-other. - — ' 

If this is a PROGRAMGROUP, then the type of program has no meaning. 

The Visibility attribute defines whether this entry is visible in the Start- 
A-Program list. 

ProgramTitle is the title for this program. No leading or trailing blanks 
are preserved by the Shell API. 

IconFileName defines the icon file associated with this program. 



typedef struct pib 
PROGTYPE 



char 

char 

char 

char 

XYWINSIZE 

char 

short 

char 

short 

char 
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ExecutableFileName defines the executable file that will be run when 
this program is started. 

StartupDirectory defines the subdirectory that will be the current drive 
and directory when the program starts running. 

InitialPosition is the suggested position and size to be used on the first 
WINCreateWindow call. If all values are 0, then the Shell will provide an 
initial size and position. 

HelpString is a short informative piece of help information for this pro- 
gram. This text will be displayed whenever general help is requested for 
this program. 

EnvironLength is the length of the EnvironString. 

EnvironString defines the environment variables to be passed to the pro- 
gram when it is started. This string is in the format required by DOS, i.e. 
a set of ASCIIZ strings, the complete set of which is terminated by a null 
character. 

Parameter Length is the length of the ParameterString. 

ParameterString defines the parameter to be passed to the program, via 
its “Command Line” when it is invoked. 

Each entry in ParameterArray is a structure, as follows. 

Definition 



typedef struct 
WORD 
BYTE 
short 
char 



parameterdescriptor { 
ParameterType ; 

ParameterSubtype; 

PstringLength; 

ParameterString [PStringLength] ; 
/* Initial path for FileSystem 
when User Selected File Name 
OR default input string */ 



> PARAMETERDESCRIPTOR *PARAMETERDE SCR I PTORPTR ; 



ParameterType is one of three basic types. 



• File name 

When ParameterSubtype will be one of the following 
— User selected - by definition, must exist 
— User entered - must exist 
— User entered - must not exist 
— User entered - may or may not exist 

• Free format 
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• Constant 

ParameterSubtype is one of the defined filename subtypes if Parameter- 
Type is File-Name, otherwise it is undefined. 

PStringlength is the length of ParameterString excluding the ter- 
minating zero. This is the length before any substitutions have taken 
place. 

ParameterString is an ASCIIZ input string for the program. The mean- 
ing of ParameterString depends on ParameterType. These meanings are 
shown below. 



Type Meaning of ParameterString 
constant 

Input Parameter for the program, 
user selected filename 

Initial path to use for file selection when calling the FileSys- 
tem. 

free format 

String from which the input parameter string is constructed, 
which may include prompting the user for the actual param- 
eter. 



Definition 

typedef struct ProgramEntry { 

HANDLE ProgramHandle; 

PROGTYPE P r o gr amType ; 

/* Program/Group Handle Flag */ 
char InvisibleFlag; 

/* zero if ENTRY is visible on screen, 

non-zero if hidden */ 
char IconFileName [&maxpathl . +1] ; 

char ProgramTitle [60+1] ; 

> PROGRAMENTRY +PROGRAMENTRYPTR ; 

Where 

ProgramHandle is the program/group handle. 

Program Type is PROGRAM or PROGRAMGROUP. In the case of 
PROGRAM then the information as to what type of program this is is 
included. The type can be Presentation Manager, non-Presentation 
Manager- Windowed, and non-Presentation Manager-other. 

InvisibleFlag is VISIBLE if this entry appears when this group is 
displayed by the Shell, or INVISIBLE if the entry is not shown in the 
visible list. It does NOT refer to the visibility status of any windows 
belonging to this entry. 
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IconFileName is a far pointer to an ASCIIZ filename string which is 
where the icon definition for this entry can be found. The pointer may be 
NULL in which case no icon is defined. 

Program Title is a character array containing the program title for this 
entry. The maximum length is 60. No leading or trailing blanks are 
preserved by the Shell API. 

Definition 



typedef struct swcontrol { 



char 


SwTitle [60+1] ; 




HANDLE 


WindowHandle; 


/* 


HANDLE 


IconHandle; 


/* 


HANDLE 


ProgramHandle 


/* 


WORD 


Processld; 


/* 


WORD 


Sessionld; 


/* 


BYTE 


SwitchFlagA; 




BYTE 


SwitchF 1 agB ; 





> SWCNTRL * SWCNTRLPTR ; 



0 if no window */ 

0 if no icon */ 

0 if not an installed program 
For this entry */ 

For this entry */ 



*/ 



Where 

SwTitle is the ASCIIZ title for this entry. It must be a non-null string in 
order to define a valid switch list entry. 

WindowHandle is the handle of the main window belonging to this 
entry. (0 means that there is no window, in which case this is a non- 
Presentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 

ProgramHandle is the program handle that was used to start the pro- 
gram resulting in this entry in the switch list. Only items in the switch 
list that have a program handle entry can be included in the SAVE CON- 
FIGURATION function as these are the only programs that the Shell 
knows how to get started. 

Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session id is gen- 
erated by DOS when starting a new session running. This is a read only 
field and may NOT be changed by the user. 

SwitchFlagA defines the visibility of an entry in the Switch List. It is a 
byte with ONE of the following values: 



NOT_VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value == 0) 

— NOT- VISIBLE means that this entry will not appear in the 
visual switch list, but can be selected by the user by using the 
Jump- Application hotkey, or, if it is a Presentation Manager 
application, making a direct selection on one of the windows 
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belonging to that application. 

— NOT_ SELECTABLE means that this entry is not enabled for 
selection. (On a colour screen it will appear grayed.) 

— SWL_ NORMAL means that this entry is both visible and 
enabled for selection. (This is the default when 0 is given.) 

SwitchFlagB defines the response of this entry to the 

Jump- Application hotkey. It is a byte with ONE of the following 

values: 

JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DI SABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be activated as a 
result of pressing the Jump- Application hotkey. 

— JUMP- DISABLED means that this entry will not be activated 
as a result of pressing the Jump- Application hotkey. The appli- 
cation can still be activated by directly selecting the entry in the 
Switch List (if the entry is visible and enabled) or, if it is a Presen- 
tation Manager application, by making a direct selection on one of 
the windows belonging to that application. 

Definition 

typedef struct SWBlock { 

WORD SwNumber; /* Number in SwListArray */ 

SWENTRY SwListArray [SwNumber] ; 

> SWBLOCK * SWBLOCKPTR ; 

Where 

SwNumber is a count of the number of array entries returned. 

SwListArray is an array with the given number of entries of SWENTRY 

structures. 

The SWENTRY structure is shown below. 

Definition 

typedef struct swentry { 

HANDLE SwHandle; /* Switch list handle for this entry */ 

SWCNTRL SwControl ; 

> SWENTRY * SWENTRYPTR ; 

Where 

SwHandle is the Switch List handle for this entry. 

SwControl is the SWCNTRL structure as given below. 

Definition 
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typedef struct swcontrol { 



char 


SwTitle [60+1] ; 






HANDLE 


WindowHandle; 


/* 


0 if no window */ 


HANDLE 


IconHandle; 


/* 


0 if no icon */ 


HANDLE 


ProgramHandle 


/* 


0 if not an installed program */ 


WORD 


Processld; 


/* 


For this entry */ 


WORD 


Sessionld; 


/* 


For this entry */ 


BYTE 


SwitchFlagA; 






BYTE 


SwitchFlagB; 







> SWCNTRL * SWCNTRLPTR ; 

Where 

SwTitle is the ASCIIZ title for this entry. It must be a non-null string in 
order to define a valid switch list entry. 

WindowHandle is the handle of the main window belonging to this 
entry. (0 means that there is no window, in which case this is a non- 
Presentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 

ProgramHandle is the program handle that was used to start the pro- 
gram resulting in this entry in the switch list. Only items in the switch 
list that have a program handle entry can be included in the SAVE CON- 
FIGURATION function as these are the only programs that the Shell 
knows how to get started. 

Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session id is gen- 
erated by DOS when starting a new session running. This is a read only 
field and may NOT be changed by the user. 

SwitchFlagA defines the visibility of an entry in the Switch List. It is a 
byte with ONE of the following values: 

NOT_VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value == 0) 

— NOT_ VISIBLE means that this entry will not appear in the 
visual switch list, but can be selected by the user by using the 
Jump- Application hotkey, or, if it is a Presentation Manager 
application, making a direct selection on one of the windows 
belonging to that application. 

— NOT- SELECTABLE means that this entry is not enabled for 
selection. (On a colour screen it will appear grayed.) 

— SWL_ NORMAL means that this entry is both visible and 
enabled for selection. (This is the default when 0 is given.) 

SwitchFlagB defines the response of this entry to the 

Jump- Application hotkey. It is a byte with ONE of the following 

values: 
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JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DISABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be activated as a 
result of pressing the Jump-Application hotkey. 

— JUMP- DISABLED means that this entry will not be activated 
as a result of pressing the Jump-Application hotkey. The appli- 
cation can still be activated by directly selecting the entry in the 
Switch List (if the entry is visible and enabled) or, if it is a Presen- 
tation Manager application, by making a direct selection on one of 
the windows belonging to that application. 

Definition 

typedef struct swentry { 

HANDLE SwHandle; /* Switch list handle for this entry */ 

SWCNTRL SwControl ; 

> SWENTRY * SWENTRYPTR ; 

Where 

SwHandle is the Switch List handle for this entry. 

SwControl is the SWCNTRL structure as given below. 

Definition 

typedef struct swcontrol { 

char SwTitle [60+1] ; 



HANDLE 


WindowHandle; 


/* 


0 if no window */ 


HANDLE 


IconHandle; 


/* 


0 if no icon */ 


HANDLE 


ProgramHandle 


/* 


0 if not an installed program */ 


WORD 


Processld; 


/* 


For this entry */ 


WORD 


Sessionld; 


/* 


For this entry */ 


BYTE 

BYTE 


SwitchFlagA; 

SwitchFlagB; 



> SWCNTRL * SWCNTRLPTR ; 

Where 

SwTitle is the ASCIIZ title for this entry. It must be a non-null string in 
order to define a valid switch list entry. 

WindowHandle is the handle of the main window belonging to this 
entry. (0 means that there is no window, in which case this is a non- 
Presentation Manager entry.) 

IconHandle is the handle to access the icon for this entry. 

ProgramHandle is the program handle that was used to start the pro- 
gram resulting in this entry in the switch list. Only items in the switch 
list that have a program handle entry can be included in the SAVE CON- 
FIGURATION {unction as these are the only programs that the Shell 
knows how to get started. 
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Processld is the DOS process id for this entry. 

Sessionld is the session identifier for this entry. The session id is gen- 
erated by DOS when starting a new session running. This is a read only 
field and may NOT be changed by the user. 

SwitchFlagA defines the visibility of an entry in the Switch List. It is a 
byte with ONE of the following values: 

NOT_VISIBLE No entry in the visual list 

NOT_SELECTABLE Visible, but disabled (grayed) 

SWL_NORMAL Visible and enabled (default value == 0) 

— NOT_ VISIBLE means that this entry will not appear in the 
visual switch list, but can be selected by the user by using the 
Jump- Application hotkey, or, if it is a Presentation Manager 
application, making a direct selection on one of the windows 
belonging to that application. 

— NOT- SELECTABLE means that this entry is not enabled for 
selection. (On a colour screen it will appear grayed.) 

— SWL_ NORMAL means that this entry is both visible and 
enabled for selection. (This is the default when 0 is given.) 

SwitchFlagB defines the response of this entry to the 

Jump- Application hotkey. It is a byte with ONE of the following 

values: 

JUMP_ENABLED Will appear in the round robin sequence 

JUMP_DISABLED Will not appear in the round robin sequence 

— JUMP- ENABLED means that this entry will be activated as a 
result of pressing the Jump-Application hotkey. 

— JUMP- DISABLED means that this entry will not be activated 
as a result of pressing the Jump-Application hotkey. The appli- 
cation can still be activated by directly selecting the entry in the 
Switch List (if the entry is visible and enabled) or, if it is a Presen- 
tation Manager application, by making a direct selection on one of 
the windows belonging to that application. 

Definition 



typedef struct 


xywinsize { 






short 


XPos ; 


/* 


X position of Window */ 


short 


YPos ; 


/* 


Y position of Window */ 


short 


XSize; 


/* 


X extent of Window */ 


short 


XSize; 


/* 


Y extent of Window */ 


word 


WinFlag; 


/* 


MINIMISED or MAXIMISED 
or INVISIBLE or NORMAL (0) */ 



> XYWINSIZE *XYWINSIZEPTR; 
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4.1 Window management functions 

4.1.1 Window Manager Architecture 

4. 1.1.1 The Window 

A window is the standard input and output tool of a Presentation 
Manager application program. Some Presentation Manager applications 
use a window to display text and graphics on the system screen and to 
process input from the system keyboard, mouse, and timer. In a virtual 
sense, a window provides the same input and output capabilities as a com- 
plete graphics terminal, but it does so without requiring complete control 
of the system’s actual hardware resources. 

Windows are identified by a window handle which uniquely identifies the 
window. 

All windows in the system are associated with a particular message queue. 
A message queue is associated with a particular thread; a thread may have 
only one message queue. Windows are always associated with the message 
queue that was associated with the thread that created with the window. 
More than one window can be associated with a particular message queue. 

Though there is an association between a window and its message queue 
thread, a window handle may be accessed by all threads and processes. 

For more information on Message Queues, see the "Message Manager" sec- 
tion. 



4. 1.1. 2 Window Procedures and Window Messages 

Every window in the system has a procedure associated with it called the 
"Window Procedure". The window procedure, also called the "Window 
Proc", controls all aspects of a window: what it looks like, how it responds 
to state changes, how it processes input, etc. 

The information passed to a window procedure is called a "Window Mes- 
sage". A window message is made up of five parts, which correspond to 
the four arguments of the window proc and its return value: 



HWND hwnd 

unsigned msg 
ULONG lParaml 

ULONG !Param2 



Handle of window receiving the message 
Msg ID identifying the message 

ULONG parameter (content depends on message ID) 
ULONG parameter (content depends on message ID) 



ULONG reply - 32 -bit return value (content depends on message ID) 
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The message ID defines the message. The contents of lParaml and 
lParam2, and whether or not a return value is required, depend on the 
semantics of the message as defined by the message ID. 

For more information on window messages and some rules for their use, 
see the "Message manager" section. 



4. 1.1. 3 Window Classes and Instances 

Every window is an "instance" of a particular window "class". The win- 
dow class defines the window procedure to be used, as well as other infor- 
mation that is shared by all instances of the class. Before an instance of a 
particular class can be created, the window class must be registered with 
the window manager. 

There are a number of preregistered window classes available to applica- 
tions, that are used to implement menus, scroll bars, pushbuttons, etc. All 
of these preregistered classes are explained in detail later. 

Window classes are identified by the "class name". Class names are nor- 
mally specified as far pointers to standard zero-terminated strings. Case is 
significant in class name strings. 

Instead of a far pointer to a string, preregistered class names are specified 
as a 32-bit value with Oxffff in the hi word, and a small integer in the low 
word. The names of these special class name constants begin with 
"WC_": 



Class Name 

Description 

WC_ FRAME 

Standard top-level window frame class 
WC_ DIALOG 

Standard dialog box window class 
WC_ BUTTON 

Pushbuttons, checkboxes, and radio buttons 

WC-EDIT 

Text editing fields 

WC_ STATIC 

Static display items such as text strings and icons. 
WC_ LISTBOX 

Lists of text that the user can choose from. 
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WC-MENU 

Menus 

WC_ SCROLLBAR 
Scroll bars 

WC_ MINMAXBOX 

Minimize/Maximize pushbuttons 

WC-SIZEBORDER 

Window sizing border 



4. 1.1.4 Public and Private Window Classes 

There are two kinds of window classes: public classes and private classes. 
Applications can create windows of private classes only within the process 
in which the class was registered. Private window class names need only 
be unique for that process; more than one application may register private 
window classes with the same class name. 

Public window classes are window classes that can be used in any process 
context to create window instances. Public class window procedures must 
be callable from any process/ thread context, so they must be defined as 
part of a dynalink library. Public class names must be unique for all 
applications; by convention, public class names should contain the module 
name as part of their name. For example: 

"ModuleName . ClassName" 

Window instances created from public or private classes can be used by 
any process in the system; the "public" and "private" terms refer only to 
the scope of the window class when used to create a window. 



4. 1.1. 5 Window Attributes 



4-1. 1.5.1 Window Style 

The "Window Style" is a 32-bit value that controls the appearance and 
behavior of a window. The window style is specified by combining various 
style values together with the OR operator. The meaning and interpreta- 
tion of the 32 style bits depends on the window class. There are a few 
standard style bits that apply to all window classes, however. These 
styles, whose names begin with "WS_", are restricted to the high order 16 
bits of the window style; this leaves the lower 16 bits available for use and 
interpretation by the window procedure of the window class. 



161 




Windows Presentation Manager Reference 



4- 1.1. 5. 2 Class Style 

In addition to window styles, there are styles which apply to all the win- 
dows of a given class. These are used in a similar way to Window Styles, 
except that they are specified when a Window Class is registered and then 
apply to ALL windows of that class. These styles have names beginning 
with "CS_" and are 32-bit values. 



4-1. 1.5.8 Window Rectangle and coordinates 

All window positions and sizes are specified in "window coordinates". 
Window coordinates are in pixel sized units, with the origin (0, 0) at the 
bottom left corner of a window. 

Every window has a rectangle associated with it that describes the size 
and position of the window on the screen. The coordinates of this RECT 
structure are in window coordinates. 

See the section, “Rectangle Functions”, for more information on the 
RECT structure. 



4. 1.1. 5. 4 Window ID 

All windows have an ID, which is a 16-bit value that is specified by the 
application when the window is created. The window ID can be used to 
refer to the window with that ID. 



4. 1.1. 5. 5 Window Text 

Many classes of windows have a string associated with them, called the 
"Window Text". This string is often displayed in the window. 



4. 1.1. 5. 6 Window Words 

For window classes registered by applications, it is possible to reserve 
extra memory for each window that can be used by the window procedure 
to store any extra information that may be required for the window class. 

When the window class is registered, the number of extra bytes to reserve 
is specified. Every window instance of that class will have these bytes allo- 
cated and initialized to 0, which can be read and modified by the applica- 
tion or window procedure. 
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The WinQueryWindowUIntQ, WinSetWindowUIntQ, WinQueryWindowU- 
Long(), and WinSetWindowULongQ functions are the only means for 
accessing window words. 



4. 1.1.6 Window Relationships 

Main application windows are called "top level" windows. All of these 
windows are arranged in an overlapping fashion: you cannot see any part 
of a window overlapped by windows above it. 

Windows may also contain other windows. Windows that contain other 
windows are called "Parent Windows"; the windows within the parent are 
called "Child windows". Child windows are always clipped to the parent; 
only the part of a child that lies within the parent’s window rectangle are 
visible. 



Windows that share the same parent are called "Sibling Windows". Like 
top level windows, siblings are arranged in an overlapping fasion. All 
sibling windows are linked together. The first window on the list is con- 
sidered the " Top window" of the list; the last window is known as the 
"Bottom window". Since all siblings are arranged in overlapping order 
this order represents the Z-axis ordering of the windows. 

All children of a window, and their children, etc., are call the "Descen- 
dants" of that window. 

Below is a diagram illustrating one possible arrangement of some windows 
on the screen. The next diagram shows the parent/child relationships of 
these windows. 

Notice that the windows are arranged in a tree, with a special window 
called the "Desktop window" at the top of the tree. Windows A, B, and C 
are top level windows, which are all children of the desktop window. The 
window handle of the desktop window is not available to the application; 
for those functions that require a parent window handle, NULL is used to 
indicate the desktop window. 

There are a few important points to note from this diagram. Window J 
illustrates how windows are always contained within their parent. Win- 
dows A, B, and C illustrate how windows are obscured by siblings above 
them. 

The actual window clipping and exclusion rules for windows is described in 
"Window Drawing Management Architecture". 
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Figure 4.2 Parent/Child relationships of Previous Diagram 



4. 1.1.7 Window Owners and Owned Windows 

When a window is created, an "owner window" may be specified. The win- 
dow is said to be an "owned window" of the owner window. 

The owned and owning relationship between windows may be specified by 
the application. The effect of owning or being owned by a window 
depends on whether the windows involved are top level windows or child 
windows: 

• Child windows may send notification messages to their owner win- 
dows. 

• When a top level window is hidden, minimized, or destroyed, other 
top level windows owned by that window are hidden or destroyed. 



4. 1.1. 8 Window States 

A window can be visible or invisible. An invisible (or "hidden") window is 
simply made invisible. Its size and position remain the same, as do its 
parent and owner windows. However, any drawing in the window is not 
shown on the screen. The visible state is controlled by the WS_ VISIBLE 
window style bit. 

Windows can also be disabled. A disabled window is still visible, but it 
does not respond to mouse input. Windows are normally enabled. The 
enabled state is controlled by the WS_ ENABLED window style bit. 

Some window classes support other window states in addition to the visi- 
ble and enabled states. These states are typically changed and queried 
with window messages. 



4. 1.1. 9 ObjectWindows 

Windows do not necessarily have to be a parent or child of a window on 
the screen. Windows that are not part of the desktop window parent tree 
are called "object windows". They have a window procedure like other 
windows, and thus can be sent messages. Object windows can also be 
owned by other windows (either object or normal), and they can have child 
windows. But, because object windows are not part of the desktop win- 
dow tree, it can’t be made visible on the screen. 

Windows whose parent window handles have the value of 
HWND_ OBJECT are considered object windows. It is possible to change 
the parent of a window with WinSetParentQ. This function can be used to 
make a normal window an object window by setting its parent to 
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HWND_ OBJECT or to make an object window a normal window by set- 
ting its parent to another normal window. 

Object windows have a size and position like other windows. If the object 
window is later given a parent window, the position is relative to the top 
left corner of the new parent. 

Object windows are also known as "Orphaned" windows, as they are win- 
dows without parents. 



4.1.1.10 Window Subclassing 

"Window Subclassing" refers to either modifying the behavior of an 
instance of a window class, or creating a new window class using an exist- 
ing window class. In either case, the subclass window procedure is a 
"hook" into the normal window procedure. The subclass window proc 
may process any message send to the window, or choose to pass it on to 
the standard window procedure, or both. In this way it is possible to 
modify the behavior of a window without rewriting the entire window pro- 
cedure. 

To subclass a window instance, it is simply necessary to replace the 
window’s window procedure with a new window procedure. The previous 
window procedure is called in place of WinDefWindowProcQ by the new 
window procedure. The WinSubclassWindow() function is used to sub- 
class a window. 

To create a subclass from an existing class, it is necessary to register a new 
window class with a window procedure that calls the existing class window 
procedure in place of WinDefWindowProc(). The window proc address 
and other information necessary to register a subclass may be obtained 
with the WinQueryClassInfoQ function. 



4.1.1.11 Special Windows 

There are a number of special windows in the system. These special win- 
dows generally have to do with the routing of mouse and keyboard input 
and commands. 



4-1.1.11.1 Active Window 

The "Active Window" is the top level window that either has or contains 
the "focus window" (see below). It is usually the topmost window, and is 
hilighted in some way. The active window is the window that the user is 
currently interacting with. 
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4-1.1.11.2 Focus Window 

The "Focus Window" is the window that will recieve all keyboard input. 
See the "Input Manager" for more information on the focus window. 



4.1.1.11.8 Capture Window 

The "Capture Window" is the window that recieves all mouse input, even 
when the mouse is not over the window. There is normally no capture 
window; in that case mouse input is routed to the window underneath the 
mouse cursor. 



4 .I.I.H .4 System Modal Window 

The "System Modal Window" is a special top level window that recieves 
all mouse and keyboard input. Input may also routed to one of its chil- 
dren. All other top level windows behave as if they are disabled; no 
interaction is possible. 



4.1.1.12 Window Management Routines 

4-1.1.12.1 Window Class Styles 



Window Class Styles 
Meaning 

CS-SAVEBITS 

This style controls whether or not the screen image of the 
area underneath the window is saved when the window is 
made visible. For more information, see "WinShowWin- 
dow()". 

CS_ SIZEREDRAW 

This style determines whether a window should be redrawn 
when sized. This style should be used for a window whose 
contents are sensitive to the size of the window. For exam- 
ple, the data in some windows can be scaled up or down to 
fit the size of the Client Area. In other windows, the data 
remains the same size whatever the size of the window - it is 
merely clipped if the window is made smaller. The 
CS_ SIZEREDRAW style should be used in the first case but 
not in the second. For more information, see 
" WM_ C ALC V ALIDRECTS " . 
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CS_ SYNCPAINT 

Window will be synchronously repainted. See "Window 
Painting After Window Rearrangement" for more informa- 
tion. 

CS_ PARENTCLIP 

This style controls how the window is clipped when drawing 
into it. For more information, see "Window Drawing 
Management". 



4-1.1.12.2 Standard Window Styles 



Standard Window Styles 
Meaning 

WS_ VISIBLE 

Window is visible. The absence of this bit indicates that a 
window is invisible. See "WinShowWindow()" for more 
information. 

WS_ DISABLED 

Window is disabled. The absence of this bit indicates that a 
window is enabled. See " WinEnableWindowQ’ for more 
information. 

WS-CLIPCHILDREN 

Causes child windows to be excluded when drawing in the 
window. Normally, child windows are not excluded. See 
"Window Drawing Management" for more information. 

WS-CLIPSIBLINGS 

Causes sibling windows to be excluded when drawing in the 
window. Normally, siblings are not excluded. See "Window 
Drawing Management" for more information. 

WS_ GROUP 

Used to identify the dialog items that make up a "group". 
See the "Dialog Manager" for more information. 

WS-TABSTOP 

Used to identify dialog items that will be enumerated when 
the TAB key is pressed. See "Dialog Manager" for more 
information. 

WS-SYSMODAL 

The window is a system modal window. This means that no 
other window -- even windows belonging to other applica- 
tions — can receive the focus until the window relinquishes 
control (i.e. is destroyed with WinDestroyWindow). This 
style is generally used for message boxes and other critical 
error dialog boxes. 
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WS-MOVENOTIFY 

A window with this style causes a \VM_MOVE message to 
be generated by the window manager when it is moved rela- 
tive to the screen. See the ’WM_MOVE’ message descrip- 
tion for more detail. 



4- 1.1. IS. 8 Window Class Routines 



WinRegisterClass 



Format 



BOOL WinRegisterClass (hab, IpszClassName, 

lp fnWndProc , 
styleClass , 
cbWndExtra, idModule) 

LPSTR IpszClassName; 

FARPROC lp fnWndProc; 

ULONG sty leDe fault ; 

INT cbWndExtra; 

UINT idModule; 

HAB hab; 

Description 

This function registers a window class having the 
supplied characteristics with the window manager. 
Returns TRUE if successful, FALSE otherwise. 

Once registered, the class name may be used to 
create windows of that class. 

IpszClassName is a far pointer to the class name 
string, or one of the WC_* class name constants 
to specify any of the preregistered classes. The 
actual class name to be used for the preregistered 
classes may be found in the description of the class 
elsewhere in this manual. 

lpfnWndProc is the window procedure address to 
use when creating instances of this class. 

styleClass specifies the window class style. 

will 

cbWndExtra specifies the number of bytes of win- 
dow words to reserve when a window is created. 

idModule is the module handle that contains the 
code of the window procedure, returned by the 
DOS DosLoadModule call. If idModule is NULL, 
the class is assumed to be a private class. Oth- 
erwse, idModule must be a module handle of a 
dynamic link library containing th code of the 
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window procedure. The class name must also be 
unique; this can be achieved by naming the class 
by prepending the module name: 

"ModuleName . ClassName" 

Notes Registering a public class with the same name as 
an existing public class replaces the existing class. 
Registering a private class with the same name as 
another private class of the same process fails and 
WinRegisterClassQ returns FALSE. Applications 
should avoid registering private classes with the 
same name as an existing public class. Private 
classes with the same name as a public class 
preempt the public class for that process. 

See "Public and Private Window Classes". 

Win Query ClassName 



Format 



INT WinQueryClassName (hwnd, lpchBuffer, cchBuf ferMax) 
HWND hwnd ; 

LPSTR lpchBuffer; 

INT cchBufferMax; 

Description 

This function copies the null terminated class 
name string of the specified window into 
*lpszBuffer, returning the length of the string not 
including the null termination character. If the 
class name is longer than cchBufferMax, it is trun- 
cated at (cchBufferMax - 1) characters; the string 
is always null terminated. 

If the window is of any of the preregistered WC_ * 
classes, the string returned will be of the form 
"#n", where n is a single digit corresponding to 
the value of the WC_ * class name constants. 



4.1.1.12.4 Creating and Destroying Windows 

typedef struct CREATESTRUCT { 

UCHAR FAR * IpPresParams ; 

UCHAR FAR *lpCtlData; 

UINT id; 

HWND hwndlnsertBehind; 

HWND hwndOwner; 

HWND hwndParent; 

INT cy; 

INT cx; 

INT y; 
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INT x; 

ULONG style; 
LPSTR IpszName; 
LPSTR IpszClass; 
> CREATE STRUCT; 



WinCreate Window 



Format 



HWND WinCreateWindow (hab, IpszClassName, 
IpszName, style, x, y, cx, cy, 
hwndParent, hwndOwner, hwnd Insert Behind, 
id, lpCtlData, IpPresParams ) ; 

LPSTR IpszClassName; 

LPSTR IpszName; 

ULONG style; 

INT x, y, cx, cy; 

HWND hwndParent; 

HWND hwndOwner; 

HWND hwndlnsertBehind; 

UINT id; 

HAB hab; 

UCHAR FAR * lpCtlData; 

UCHAR FAR * IpPresParams; 

Description 

This function creates a new window, returning the 
window handle of the window or NULL if unsuc- 
cessful. 

An instance of the window class named by 
IpszClassName is created. IpszClassName may be 
a far pointer to a registered class name string, or it 
may be one of the preregistered class names shown 
in the section, “Window Classes and Instances” . 

IpszName points to the window text, or to other 
class-specific data. The actual structure of the 
data pointed to by IpszName is class-specific, but 
it is usually a zero terminated string, which is 
often displayed in the window. 

style specifies the style of the window. Any of the 
standard WS_ style bits may be used, in addition 
to any class-specific styles that may be defined for 
that class. 

x and y specify the position of the window, in win- 
dow coordinates relative to the origin of the parent 
window (specified below), cx and cy are the hor- 
izontal and vertical dimensions of the window, also 
in window coordinate units. 
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hwndParent specifies the parent window. If 
hwndParent is NULL, a top level window is 
created. If hwndParent is HWND_ OBJECT, an 
object window is created. 

hwndOwner is the ’owner’ window. In the case of 
windows with notification codes (like controls), the 
owner is the window to notify when something 
happens to the control. When a window gets des- 
troyed, all windows it owns get destroyed also. 

hwndlnsertBehind specifies the Z-ordering of the 
newly created window in relation to another win- 
dow. The new window is placed immediately 
behind the window specified. hwndlnsertBehind 
can take the values HWND-TOP and 
HWND_ BOTTOM to put the new window at the 
top or bottom of the Z-ordering, respectively. 

id is an application-specified value typically used 
to identify a window. For example, all controls of 
a dialog must have unique IDs so the owner win- 
dow when notified can determine which control has 
notified it. For standard formatting of frame con- 
trols, standard IDs must be used identifying each 
control type. See Frame Formatting. 

lpCtlData is a far pointer to class-specific data 
that may be used to pass information to the 
window procedure as the window is created. This 
field is available to the window proc (as are all of 
the other parameters above) in the CREATES- 
TRUCT structure passed with the WM_ CREATE 
message. It may also be accessed at any time by 
the WM_ SETWINDOWPARAMS and 
WM_ QUERYWINDOWP ARAMS messages. 

IpPresParams is a reserved field, and must have a 
value of zero. 

Notes A window is normally created enabled and invisi- 
ble. See the list of the standard window styles for 
more information on the initial state of a created 
window. 

Messages may be recieved from other processes or 
threads when WinCreateWindow() is called. 

WinCreateWindowf) sends the WM_ CREATE 
message to the window being created. If the win- 
dow is created with the WS_ VISIBLE style, Win- 
CreateWindow() will call WinShowWindowQ, 
which may cause additional messages to be sent. 
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The WM—SIZE message is NOT sent by Win- 
CreateWindowQ while the window is being 
created. Any required size processing can be per- 
formed during the processing of the 
WM_ CREATE message. 

Since windows are often created initially with zero 
height or width and sized later with a non-zero 
size, it is a good idea to avoid performing any 
size-related processing if the size of the window is 
zero. 

It should be noted that there is no limitation to 
the size and position specified for a window within 
the number range permitted for the size and posi- 
tion parameters. This means that an application 
can create windows which are larger than the 
screen or which are positioned partially or wholly 
off the screen. 

It should be remembered, however, that the user 
interface for manipulation of window sizes and 
positions is affected if part or all of the window is 
off the screen. It is recommended that part of the 
title bar is left on the screen, if the window has 
one, to allow the user to move the window around. 

These considerations apply to all windows, but 
particularly to Standard windows. 

WinDestroy Window 



Format 



BOOL WinDestroyWindow (hwnd) 

HWND hwnd; 

Description 

This function destroys a window and all its descen- 
dants. Before the specified window is itself des- 
troyed, all other top level windows owned by hwnd 
are destroyed. Returns TRUE if sucessful, FALSE 
if hwnd is an invalid window handle or is not asso- 
ciated with the current thread. 

Notes If hwnd is locked, WinDestroy Window() does not 
return until the window is unlocked. See the sec- 
tion on "Window Locking". 

Messages may be received from other processes or 
threads. 

Messages sent before WinDestroyWindowQ 
returns: 
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Message 

When Sent 
WM_ DESTROY 

Always sent to the window being des- 
troyed after the window has been hidden 
from the screen, but before its children 
have been destroyed. The message is sent 
first to the window being destroyed, then 
to the children as they are destroyed. 
Therefore, during the processing of the 
WM_ DESTROY message, it can be 
assumed that all the children still exist. 

WM_ KILLFOCUS 

Sent if the window being destroyed or 
any of its descendants is the focus win- 
dow. 

WM_ ACTIVATE 

Sent with LOUINT(lParaml) == FALSE 
if the window being destroyed is the 
active window. 

WM_ OTHERWINDOWDESTROYED 

Sent to all top level windows if hwnd or 
any of its descendants has been 
registered with WinRegisterWindowDes- 
troy(). See "Window Locking". 

WM_ RENDERALLFMTS 

Sent if the clipboard owner is being des- 
troyed, and there are unrendered formats 
in the clipboard. See the "Clipboard 
Manager" . 

If the application has associated a presentation 
space with the window, it must disassociate the PS 
(using GpiAssociate(hgpi, NULL) ) before calling 
WinDestroyWindowQ. If it does not do so, Win- 
DestroyWindow returns an error. Alternatively, 
the application can destroy the PS before it des- 
troys the window. 



WM_ CREATE 



Format 



WM_CREATE 
lParaml : 
lParam2 : 
Returns : 



BYTE EAR *lpCtlData; 

CREATESTRUCT FAR *lpCreateStruct; 
BOOL fError ; 
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Description 

This message is sent from WinCreateWindow(). 
The app uses this message for any window initiali- 
zation that needs to be done. The window pro- 
cedure returns TRUE to indicated that some error 
occured, and the window should not be created 
(i.e., WinCreateWindowQ should return NULL), 
and FALSE to indicate that creation should 
proceed normally (and the window should be 
created). 

lparaml contains the Control Data parameter 
which is passed to WinCreateWindowQ. lParam2 
contains a far pointer to a CREATESTRUCT 
structure, whose fields correspond to the parame- 
ters of WinCreateWindowQ. 



WM_ DESTROY 



Format 



WM_DESTROY 
lParaml: 0; 

lParam2 : OL; 

Returns : OL ; 

Description 

This message is sent when WinDestroyWindowQ is 
called, after the window has been removed from 
the screen. The WM_ DESTROY message is used 
to destroy window instance related data, before 
the window structure has been freed. 



4-1.1.12.5 Enabling or Disabling a Window 



WinEnable Window 



Format 



BOOL WinEnableWindow (hwnd, fEnable) 

HWND hwnd; 

BOOL f E n ab 1 e ; 

Description 

This routine is used to enable or disable a window. 
If fEnable is TRUE, hwnd is enabled, otherwise 
hwnd is disabled. The enabled state is changed by 
setting or clearing the WS_ DISABLED window 
style bit, as appropriate. Returns TRUE if the 
window was previously enabled, FALSE if it was 
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not. 

If the enable state is changed, a WM_ ENABLE 
message is sent before WinEnableWindowQ 
returns. This message is sent only if a state 
change occurs. 

If the window is disabled, and it or one of its chil- 
dren is the focus window, then WinSetFocusQ is 
called to set the focus window to NULL. However, 
the focus window may be set to a disabled window 
after the window is disabled. 

When a window is disabled, its children are impli- 
citly disabled, although they are not send the 
WM_ ENABLE message. 

Notes A disabled window does not respond to mouse 

input, but may still recieve keyboard input if it is 
the focus window. 

This function may be used to enable or disable 
ANY window, including the standard controls such 
as pushbuttons, scrollbars, etc. 

Typically, a window changes its appearance when 
disabled. For example, a disabled pushbutton is 
displayed with halftone text. 



WinlsWindowEnabled 



Format 



BOOL WinlsWindowEnabled (hwnd) 

HWND hwnd; 

Description 

Returns TRUE is hwnd is enabled, FALSE if it is 
disabled. A window is enabled if its 
WS_ DISABLE window style bit is clear and dis- 
abled if the bit is set. 



WM_ ENABLE 



Format 



WM_ENABLE 
lParaml : 
lParam2 : 
Returns : 



BOOL f Enable 

OL 

OL 
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Description 

The WM_ ENABLE message is sent from WinEna- 
bleWindowQ if a window’s enable state is chang- 
ing. If fEnable is TRUE, a previously disabled 
window has been enabled. If fEnable is FALSE, a 
previously enabled window has been disabled. 

This message is always sent before WinEnableWin- 
dow() returns, but AFTER the window enable 
state (WS_ DISABLE window style bit) has been 
changed. 

This message is sent only if a state change has 
occured. 



4-1.1.12.6 Showing or Hiding a Window 

Normally when a window is hidden, the windows underneath must redraw 
themselves clipped to the area being uncovered. However, if the 
CS—SAVEBITS style is specified, the screen image underneath the window 
is saved when the window is made visible. When the window is hidden or 
destroyed, this window image is simply replaced onto the screen, avoiding 
any window repainting. If an application draws into a window underneath 
a CS-SAVEBITS window, or if the window is sized or moved, the area of 
the saved image that is invalidated is redrawn when the window is hidden. 

Because saved screen images can take up quite a bit of memory for large 
windows, the CS-SAVEBITS class style should be used carefully. It is 
generally used for transient windows such as menus and dialog boxes, not 
for main application windows. 



WinShowWindow 



Format 



BOOL WinShowWindow (hwnd, fShow) 

HWND hwnd; 

BOOL fShow; 

Description 

This function is used to show or hide a window. If 
fShow is TRUE, the window is shown; if fShow is 
FALSE, the window is hidden. If the window is 
shown, it is made visible on the screen, and subse- 
quent drawing in the window will be visible. If the 
window is hidden, the window is removed from the 
screen and all subsequent drawing in the window 
will not be visible. 

The visible state is changed by setting or clearing 
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the WS_ VISIBLE window style bit. The 
WM_SHOW message is sent AFTER the 
WS_ VISIBLE bit is changed. WinShowWindowQ 
returns TRUE if the WS_ VISIBLE bit was previ- 
ously set, FALSE if it was clear. 

If the visible state of the window is changed, then 
the WM—SHOW message is sent before 
WinShowWindowQ returns. 

The WM_SHOW message is sent to the specified 
window before this function returns, but only if a 
state change has occured. The message is sent 
AFTER the state change occurs. 



WinEn ableWindowUpdate 



Format 



BOOL WinEnableWindowUpdate (hwnd, fShow) 
HWND hwnd; 

BOOL fShow; 

Description 

This function is similar to WinShowWindowQ, 
except that no drawing is performed. If fShow is 
FALSE, the WS_ VISIBLE window style bit is 
cleared, without removing the image of the window 
from the screen. Any subsequent drawing in that 
window will not be visible. 

If fShow is TRUE, then the WS_ VISIBLE bit is 
set, without actually causing the window to be 
redrawn. Subsequent drawing in the window will 
be visible, however. 

WinEnableWindowUpdateQ returns TRUE if the 
WS_VISIBLE bit was previously set, FALSE if it 
was clear. 

The WM-SHOW message is sent to the specified 
window before this function returns, but only if a 
state change has occured. The message is sent 
AFTER the state change occurs. 

Notes This function is usually used to disable drawing 
before making a series of changes to a window to 
prevent needless drawing. To show a window and 
ensure that it is redrawn after calling WinEna- 
bleWindowUpdateQ with fShow == FALSE, use 
WinShowWindowQ with fShow == TRUE. 
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WinlsWindowVisible 



Format 



BOOL WinlsWindowVisible (hwnd) 

HWND hwnd; 

Description 

Returns TRUE if the specified window and its 
parents are visible (i.e., have their WS-VISIBLE 
window style bits set), FALSE otherwise. 

This function does NOT simply return the state of 
the WS_ VISIBLE style bit of the specified window; 
the state of all of the parents of hwnd are tested as 
well. 

Notes WinIsWindowVisible() may return TRUE even if 
the window is completely obscured by other win- 
dows. 



WM_ SHOW 



Format 



WM_SHOW 

lParaml : BOOL fShow 
lParam2: OL 
Returns : OL 

Description 

This message is sent from WinShowWindow() after 
a visible window is hidden, or a hidden window is 
shown. If fShow is TRUE, a previously hidden 
window is being shown; if fShow is FALSE, a previ- 
ously visible window is being hidden. 

Notes In this context, "Shown" or "Hidden" refers to the 
state of the WS-VISIBLE style bit. This message 
is NOT sent when a window is obscured by other 
windows above it. 



4 -1.1 -IS. 7 Window Data Routines 



WinQuer yWindowText 

Format 



INT WinQueryWindowText (hwnd, IpszBuffer, cchBuf ferMax) 
HWND hwnd; 
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LPSTR IpszBuffer; 

I NT cchBuf ferMax; 

Description 

This function copies the null terminated window 
text of the specified window into *lpszBuffer, 
returning the length of the string not including the 
null termination character. If the window’s text is 
longer than cchBufferMax, it is truncated at 
(cchBufferMax - 1) characters; the string is always 
null termina ted. 

Notes This function simply sends a 

WM_ QUERYWINDOWP ARAMS message to the 
specified window. 

If hwnd is a window of another process, then 
IpszBuffer must point to memory that is shared by 
both processes or a memory fault may occur. 

If this function is called with a frame window han- 
dle, then the text of the title bar frame control is 
returned. 

The WM_ QUERYWINDOWP ARAMS message 
may be sent to determine the size of the string. 



WinQueryWindowTextLength 



Format 



I NT WinQueryWindowTextLength (hwnd) 

HWND hwnd; 

Description 

This function returns the length of the window 
text of the specified window, not including the 
zero-termination character. It sends a 
WM_ QUERYWINDOWP ARAMS message to the 
window to obtain the information. 



WinSetWindowText 



Format 



BOOL WinSetWindowText (hwnd, IpszText) 

HWND hwnd; 

LPSTR IpszText; 

Description 

This function sets the text of the specified window 
to the string *lpszText. IpszText is a far pointer 
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to a zero-terminated string. Returns TRUE if suc- 
cessful, FALSE otherwise. 

Notes This function simply sends a 

WM_ SETWINDOWP ARAMS message to the 
specified window. 

If hwnd is a window of another process, then 
IpszText must point to memory that is shared by 
both processes or a memory fault may occur. 

If WinSetWindowTextQ is called with a frame win- 
dow handle, the text of the title bar frame control 
is changed. See "Window Frames" for more infor- 
mation. 



WinSetWindowParams 



Format 



BOOL f Success = WinSetWindowParams (IpszText, 
lpCtlData, IpPresParams, 
rgfStatus) ; 

LPSZ IpszText; 

UCHAR EAR * lpCtlData; 

UCHAR FAR * IpPresParams; 

UINT rgfStatus; 

Description 

This function sends a 

WM_ SETWINDOWP ARAMS message. The 
parameters correspond to the parameters of the 
message. Returns TRUE if successful, FALSE oth- 
erwise. 



WinQueryWindowParams 



Format 



I NT cchText = WinGetWindowParams (IpszText, 

cchTextMax, lpCtlData, IpPresParams, 
rgfStatus) ; 

LPSZ IpszText; 

I NT cchTextMax; 

UCHAR FAR * lpCtlData; 

UCHAR FAR * IpPresParams; 

UINT rgfStatus; 

Description 

This function sends the 

WM_QUERYWINDOWPAR AMS message. The 
parameters correspond to the parameters of the 
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message. The function returns the length of the 
window text if WPM-TEXT is specified in 
rgfStatus, otherwise 0 is returned. 



WinQueryDesktopWindow 



Format 



HWND hwndDesktop = WinQueryDesktopWindow (hab, hdc ) 
HAB hab; 

HDC hdc; 

Description 

This function returns the desktop window handle 
for the device associated with hdc, or the default 
desktop window (screen) if hdc is NULL. 

The call will fail if it is issued to a device which 
does not support windowing. This is any device 
which is not the screen device. 

Notes Many of the calls that require a desktop window 
handle will accept NULL instead of the desktop 
window handle. For example, WinCreate Window 
will accept NULL for hwndParent in order to 
create a top level window, which is a child of the 
desktop window. 



4-1 .1.12.8 Window data messages 

typedef struct { 

UINT cchText; 

UINT cchTextMax; 

LPSZ IpszText; 

UCHAR FAR *lpCtlData; 

UCHAR FAR * IpPresParams ; 

> WNDP ARAMS ; 

IpszText is a pointer to the control text, or NULL. 
lpCtlData is a pointer to the control data, or NULL. 

IpPresParams is a null pointer. 

cchText is used only with the WM_ QUERYWINDOWP ARAMS message: 
the length of t text (excluding the zero termination character) is returned 
in this field. If IpszText is not NULL, this field contains the number of 
characters copie into *lpszText, not including the zero termination charac- 
ter. The maximum length in this case is cchTextMax - 1. 
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cchTextMax is used only with WM_ QUERYWINDOWP ARAMS: it con- 
tains the size in characters of the text buffer pointed to by IpszText. This 
field is ignored by WM_ SET WINDOWP ARAMS. 

rgfStatus values 

WPM—TEXT Set/Query control text 

WPM_ CTLDATA Set/Query control data 

WPM_ PRESP ARAMS Set/Query presentation parameters 



WM_ SETWINDOWP ARAMS 



Format 



WM_SETWI NDOWP ARAMS 

lParaml: CTLP ARAMS FAR * lpWndParams ; 

lParam2: ULONG rgfStatus; 

Returns: BOOL f Success; 

Description 

This message is used to set the window data for a 
window. lParaml is a far pointer to a wndparams 
structure defined above, and lParam2 contains the 
WPM_ status flags above. 

Notes If this message is sent to a window of another pro- 
cess, then *lpWndParams, and the three data 
areas pointed to by *lpWndParams, must all be in 
memory shared by both processes. 



WM_ QUERYWINDOWP ARAMS 



Format 



WM_QUERYWI NDOWP ARAMS 

lParaml: CTLP ARAMS EAR * lpWndParams; 

lParam2: ULONG rgfStatus; 

Returns: BOOL f Success; 

Description 

This message is used to query the window data for 
a window. lParaml is a far pointer to a 
wndparams structure defined above, and lParam2 
contains the WPM_ status flags above. 

Notes If this message is sent to a window of another pro- 
cess, then *lpWndParams, and the three data 
areas pointed to by *lp WndParams, must all be in 
memory shared by both processes. 
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4-1.1.12.9 Window Information Functions 



WinWindowFromID 



Format 



HWND WinWindowFromID (hwndParent, id) 

HWND hwndParent; 

UINT id; 

Description 

This function returns the child window handle of 
hwndParent that has the specified window ID. 

Notes To obtain the window handle of a particular dialog 
item, WinWindowFromID() may be called with the 
dialog box window handle and the dialog item ID 
specified in the dialog template. See the "Dialog 
Manager" for more information. 



WinMultWindowF romIDs 



Format 



INT WinMultWindowFromIDs (hwndParent, lprghwnd, 
idFirst, idLast) 

HWND hwndParent; 

HWND FAR *lprghwnd; 

UINT idFirst, idLast; 

Description 

This function is used to quickly fill an array of 
window handles that have window ID values 
between idFirst and idLast, inclusive. The window 
handles are returned in *lprghwnd. lprghwnd is 
assumed to have (idLast - idFirst + 1) elements in 
the array. The windows are stored in the array 
indexed by their window ID: a window is stored in 
lprghwnd*?*id - idFirst*?*, where id is the window 
ID of the window. If no window exists with an ID 
in the range, that corresponding element in the 
array is NULL. 

This function returns the number of window han- 
dles return in the lprghwnd array. Returns 0 if no 
window handles were returned. 

Notes This function may be used to enumerate all items 
in a dialog group with contiguous ID values, or to 
enumerate all of the frame controls. This function 
is faster than multiple calls to WinWin- 
dowFromlDQ. 
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WinQuery Window 



Format 



HWND WinQuery Windo w (hwnd, code, fLock) 

HWND hwnd; 

I NT code; 

BOOL fLock; 

Description 

WinQuery Window() returns a window handle asso- 
ciated with the specified window, depending on the 
code parameter. The available values of the code 
parameter and their effect is shown in the table 
below. If fLock is TRUE, then the window is 
returned locked, and the caller is responsible for 
unlocking it. If fLock is FALSE, the window is 
returned unlocked. See "Window Locking" 

If WinQuery Window() is used to enumerate win- 
dows of other threads, it is not guaranteed that all 
windows will be enumerated, because the Z order- 
ing of the windows might change during the 
enumeration. Use WinEnumWindow() instead: see 
"Window Enumeration". 

Available WinQueryWindowQ codes: 

WinQuery Window Codes 
Code 

QW_ NEXT 

Next window (window below) 

QW_ PREY 

Previous window (window above) 

QW_ TOP 

Top most child window 

QW_ BOTTOM 

Bottom most child window 

QW_ OWNER 

Owner of window 

QW_ PARENT 

Parent of window. Returns 
HWND_ OBJECT if object window. 



WinlsWindow 
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Format 



BOOL WinlsWindow (hab, hwnd) 

HWND hwnd; 

HAB hab; 

Description 

This function returns TRUE if hwnd is a valid win- 
dow handle, FALSE otherwise. 



WinlsChild 



Format 



BOOL WinlsChild (hab, hwndParent, hwnd) 

HWND hwndParent; 

HWND hwnd; 

HAB hab; 

Description 

Returns TRUE if hwnd is a descendant of 
hwndParent, FALSE otherwise. If hwndParent is 
NULL, this function returns TRUE if hwnd is a top 
level window. 



WinQueryWindowProcess 



Format 



UINT WinQueryWindowProcess (hwnd, lptid) 
HWND hwnd; 

UINT FAR * lptid; 

Description 

This function is used to obtain the process ID and 
thread ID associated with a window. Returns the 
process ID, or NULL if unsuccessful. The thread 
ID is returned in *lptid. If lptid is NULL, the 
argument is ignored and the thread ID is not 
returned. 



4-1 .1.12. 10 Window Size & Position Related Functions 



WinQueryWindowRect 



Format 



void WinQueryWindowRect (hwnd, lprc) 
HWND hwnd; 
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LPRECT lprc; 

Description 

This function returns the window rectangle of the 
specified window in *lprc. The rectangle is 
returned in window coordinates relative to the bot- 
tom left corner of the parent of hwnd, or the 
screen if hwnd is a top level window. 



WinSetParent 



Format 



HWND WinSetParent (hwnd, hwndNewParent, fRedraw) ; 
HWND hwnd; 

HWND hwndNewParent; 

BOOL fRedraw; 

Description 

This function changes the parent window of hwnd 
to hwndNewParent, returning its previous parent 
handle. 

If hwnd is visible and it is not an object window, 
the appropriate redrawing is performed. 

If hwndNewParent is HWND_ OBJECT, hwnd 
becomes an "object window". Object windows can 
be converted to normal windows again on the 
screen by setting their parent to another normal 
window. 

If hwndNewParent is NULL, hwnd becomes a top 
level window. 

If hwnd is visible and fRedraw is TRUE, any neces- 
sary redrawing in both the old parent window and 
the new parent window is performed. If fRedraw is 
FALSE, no redrawing is performed. This is useful 
at times when the window will be later redrawn 
anyway, such as during \VM_SIZE message pro- 
cessing. The window is essentially first hidden in 
the old parent window, and shown again in the 
new parent window. The messages sent are the 
same as with WinShowWindowQ. 

hwndNewParent may not be a child of hwnd. 

Notes This function returns an unlocked window handle. 

The WinQueryWindowQ function can be used to 
get a window’s parent. 
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WinSetOwner 



Format 



HWND WinSetOwner (hwnd, hwndNewOwner) 

HWND hwnd; 

HWND hwndNewOwner; 

Description 

This function changes the owner window of hwnd 
to hwndNewOwner, returning its previous owner 
window. hwndNewOwner may be NULL to disown 
a window. If the window was not previously 
owned, NULL is returned. 

Notes This function returns an unlocked window owner. 

The WinQueryWindow() function can be used to 
get a window’s owner. 

typedef struct { 

HWND hwnd; 

HWND hwndlnsertBehind; 

INT x, y; 

INT cx, cy; 

UINT rgfSwp; 

> SWP ; 



WinSetWindowPos 



Format 

BOOL WinSetWindowPos (hwnd, hwndlnsertBehind, 
x, y, cx, cy, rgfSwp) 

HWND hwnd; 

HWND hwndlnsertBehind; 

INT x, y, cx, cy; 

UINT rgfSwp; 

Description 

WinSetWindowPosQ is a general window position- 
ing function, used to change position, size, and Z 
ordering of any window. Returns TRUE if success- 
ful, FALSE otherwise. 

hwnd is the window to be changed. It it positioned 
x and y units from the bottom left corner of its 
parent, with the size specified by cx and cy. The 
window is inserted behind hwndlnsertBehind. 

If hwndlnsertBehind is HWND-TOP, then hwnd is 
brought to the top, relative to it siblings. If hwnd 
is a top level window, it is activated if it is brought 
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to the top. If the active window is moved behind 
another window, the new top window is activated. 

If hwndlnsertBehind is HWND_ BOTTOM, then 
hwnd is placed at the bottom relative to its 
siblings. 

Not all of these parameters must be specified. The 
rgfSwp parameter controls the interpretation of 
the parameters, and the behavior of WinSetWin- 
dowPosQ: 



WinSetWindowPos Flags 
Flag 

SWP_ SIZE 

Change the size of the window. Nor- 
mally, the size is not changed. 

SWP_MOVE 

Move the window. Normally, the win- 
dow is not moved. 

SWP_Z ORDER 

Change the window Z ordering. Nor- 
mally, the hwndlnsertBehind parameter 
is ignored. 

SWP_ NOREDRAW 

Don’t redraw changes. Normally, 
changes made are redrawn. 

SWP_ ACTIVATE 

Activate the window if the window is 
brought to the top, and deactivate the 
window if it is moved from the top to 
behind another window. The new top- 
most window is activated. Normally, the 
active window is not changed. 

SWP_ ADJUST 

Send a WM_ ADJUSTWINDOWRECT 
message before moving or sizing window. 

Notes Messages may be received from other processes or 
threads. 

If a window is made smaller and it was has the 
CS—SAVEBITS style, the saved screen image is 
used to redraw the area uncovered when the win- 
dow size changes, if those bits are still valid. See 
"Showing and Hiding Windows". 

If the CS_ SIZEREDRAW style is present, the 
entire window area is assumed invalid if sized. 
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Otherwise WM_ CALCVALIDRECTS is sent to the 
window to inform the window manager which bits 
may be possible to preserve. 

Messages sent from WinSetWindowPosQ and Win- 
SetMultWindowPosQ have specific orderings 
within the window positioning process. The process 
begins with redundancy checks and precalculations 
on every window for each requested operation. For 
example, if SWP_SHOW is present but the win- 
dow is already visible, SWP_SHOW is turned off. 

If SWP_ SIZE is present and the new size is equal 
to the old size, SWP-SIZE is turned off, etc. If the 
operations will create new results, the information 
is calculated and store away. For example, if sizing 
or moving, the new window rectangle is stored 
away for later. It is at this point that the 
WM_ AD JUSTWINDOWRECT message is sent to 
any window that is sizing or moving. It is also at 
this point that the WM_ CALCVALIDRECTS mes- 
sage is sent to any window that is sizing and 
doesn’t have the CS_ SIZEREDRAW class style. 

Once all the new window state is calculated, the 
window management process begins. Window areas 
that can be preserved are moved from the old to 
the new positions, window areas that are invali- 
dated by these operations are calculated and dis- 
tributed as update regions, etc. Once this is 
finished, and before any sync paint windows are 
repainted, the WM—SIZE message is sent to any 
windows that have changed size, 
at Next, all the sync paint windows that can be 
repainted are repainted, and the entire process in 
complete. 

If a sync paint parent window has a size sensitive 
area displayed that includes sync paint child win- 
dows, the parent will want to reposition those win- 
dows when it gets the WM_SIZE message. Their 
invalid regions will get added to the parent’s, 
resulting in one update after the parent’s 
WM—SIZE message, rather than many indepen- 
dent and later duplicated updates. 

Messages sent from WinSetWindowPosQ: 



Message 

When Sent 
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WM_ CALCVALIDRECTS 

This message is sent to determine the 
area of a window that may be possible to 
preserve as the window is sized. 

See "Window Painting" for more infor- 
mation on the 

WM_ CALCVALIDRECTS message. 

WM_ SYNCPAINT 

This message is sent when any part of a 
window with the WS_ SYNCPAINT class 
style becomes uncovered or otherwise 
requires repainting. May be sent to win- 
dows of other processes or threads. 

WM-SIZE 

This message is sent if the size of the 
specified window has changed. Sent 
AFTER the window’s size has changed. 

WM_ ACTIVATE 

If a top level window is brought to the 
top and SWP_ NOACTIVATE is not 
specified, the window is activated. In 
this case, WinSetActiveWindowQ will 
send a WM_ ACTIVATE message, and 
possibly others. See WinSetActiveWin- 
dow() for more information. 

WM-ADJUSTWINDOW ECT 

This message is sent if SWP_ ADJUST is 
specified. IParamI points to an SWP 
structure which has been filled in by 
SetWindowPosQ with the proposed 
move/size data. The windowl may 
adjust this new position by changing the 
contents of the SWP structure. It can 
change the x/y fields to adjust its new 
position; it can change the cx/cy fields to 
adjust its new size, or it change the 
hwndlnsertBehind field to adjust its new 
z-order. 



WinSetMultWindowPos 



Format 



BOOL WinSetMultWindowPos (hab, IpSwp, cSwp) 
HAB hab; 

SWP FAR * IpSwp; 

I NT cSwp; 
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Description 

This function is similar to WinSetWindowPosQ, 
except that it can be used to reposition more than 
one window at a time. IpSwp points to an array of 
SWP structures, and cSwp is the count of SWP 
structures in that array. A single call to Set- 
MultWindowPosQ is much faster and causes less 
screen updating tnan multiple calls to WinSetWin- 
dowPosQ. 

All the windows concerned must have the same 
parent. 

The fields of the SWP structure correspond to the 
parameters of SetWindowPosQ. 

Returns TRUE if any error occured, FALSE other- 
wise. 



WM—SIZE 



Format 



WM_SIZE 

LOUINT (lParaml) 
HIUINT (lParaml) 
LOUINT (lParam2) 
HIUINT (lParam2) 
Returns : 



: INT cxNew 
: INT cyNew 
: INT cxOld; 
: INT cyOld; 
OL 



Description 

This message is sent from WinSetWindowPosQ or 
WinSetMultWindowPosQ when a window’s size 
is initialized or changed. cxOld and cyOld are the 
PREVIOUS horizontal and vertical dimensions of 
the window. The LOUINT of lParaml contains 
the new width of the window, the HIUINT of 
lParaml contains the new height of the window. 

This message is NOT sent by WinCreateWindowQ 
when the window is created. Any size related pro- 
cessing must be performed during the 
WM_ CREATE message processing. 

This message is sent after the window has been 
actually sized, but before any repainting has been 
performed. Any resizing or repositioning of child 
windows, etc., that may be necessary as a result of 
the size change is usually performed during the 
processing of this message. It is generally unwise 
to do any output to the window during the pro- 
cessing of the WM—SIZE message, because the 
area drawn into may be drawn a second time after 
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the WM_ SIZE processing is complete by Win- 
SetWindowPosQ. 

The processing of this message for a window which 
is displaying an Advanced Vio presentation space 
must be carried out by WinDefAVioWindowProc. 
See the section, “WM_ SIZE Message Processing”, 
for details. 



WM-MOVE 



Format 



WM_MOVE 
lParaml: OL 
lParam2: OL 
Returns : OL 

Description 

The window manager sends a WM-MOVE mes- 
sage when a window with WS_ MOVENOTIFY 
style changes its absolute position (ie. relative to 
the origin of the screen). It is sent from Win- 
SetWindowPosQ, WinSetMultWindowPosQ, and 
WinScrollWindowQ. 

The window’s new position is obtained by calling 
WinGetWindowRect(), and can make those rectan- 
gle coordinates relative to any window by calling 
WinMapWindowPoints(). 

There are several cases where windows want to 
know if they’ve been moved. This includes the 
cases when the window doesn’t change position 
relative to its parent but does change position rela- 
tive to the screen (its absolute position). 

An example is menus. When a top level menu con- 
trol (child of the frame window) moves its absolute 
position as a result of the frame window being 
moved, the top level menu control wants to move 
any pull down menus along with its movement. 

The same goes for application / dialog box posi- 
tional grouping. In some cases a dialog box might 
want to be moved as the main window is moved, to 
clear room for other applications. 



WM_ C ALCV ALIDRECTS 
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Format 



WM_CALCVAL I DRE CTS 

lParaml: RECT FAR * IprcWindowOld; 

lParam2 : RECT FAR * IprcWindowNew; 

Returns: UINT Align; 

Description 

This message is sent from WinSetWindowPosQ and 
WinSetMultWindowPosQ to determine which areas 
of a window may be preserved if a window is sized, 
and which should be redisplayed. This message is 
NOT sent if this window has the 
CS_ SIZEREDRAW style, indicating size sensitive 
window content that must be totally redrawn if 
sized (see WinSetWindowPosQ). 

lParaml points to a rectangle structure that con- 
tains the rectangle of the window before the move. 
lParam2 points to the new window rectangle. The 
coordinates of the rectangles are parent window 
relative. This allows the application to determine 
if the window’s position has changed as well as its 
size, which can aid alignment processing. 

These rectangles may be modified by the window 
procedure to cause parts of the window to be 
redrawn and not preserved. 

The window manager will attempt to preserve the 
screen image by copying the image described by 
the old rectangle into the image described by the 
new rectangle. In this way, an application may 
control the alignment of the preserved image as 
well, by changing the origin of the first rectangle. 

If no change is made to either rectangle, the entire 
window area is preserved. If either rectangle is 
empty, the entire window area is completely 
redrawn by the operation. The message has a 
return value, Align, which can be used to instruct 
WinSetWindowPosQ how to align valid window 
bits. This return value is made up from CVR_ 
flags, as follows: 



CVR_ ALIGNLEFT 

Align with the left edge of the window 

CVR_ ALIGNBOTTOM 

Align with the bottom edge of the win- 
dow 
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CVR_ ALIGNTOP 

Align with the top edge of the window 

CVR_ ALIGNRIGHT 

Align with the right edge of the window 

CVR_ REDRAW 

The whole window is invalid 

If 0 is returned, it is assumed the application has 
changed the rectangles pointed to by lParaml and 
lParam2 itself. 

If CVR_ REDRAW is set, the whole window is 
assumed invalid. Otherwise, the remaining flags 
may be OR’ed together to get differing kinds of 
alignment. For example: 

( CVR_AL I GNLE F T | CVR_ALIGNTOP) 

Align the valid window area with the 
top left of the window. 

The WinDefWindowProc() default is to return 
CVR_ REDRAW if the window has the style 
CS_ SIZEREDRAW, and otherwise align the valid 
area with the window origin by returning 
(CVR_ ALIGNBOTTOM { CVR_ ALIGNLEFT). 

In addition, any child windows intersecting the 
source rectangle pointed to by lParaml of the 
WM_ CALCVALIDRECTS message will also be 
offset with the aligned window area. 

This functionality can be used to optimize window 
updating when tbe window is resized. For exam- 
ple, if the application returns that the window is 
to be aligned with the top left corner, and the top 
border is sized, the window’s screen data will move 
with the top border. 

In all cases, the rectangles are intersected with the 
area of the screen that is actually visible and the 
valid area of the window. That is, only the win- 
dow area that contains window information is 
copied. 

For example, consider an application that has two 
scroll bars, which are children of the client win- 
dow. When the window is resized, the scroll bars 
must be completely redrawn. By returning rectan- 
gles that exclude the scroll bars, the area of the 
scroll bars is completely redrawn, thereby preserv- 
ing only that part of the screen that is worth 
preserving. 
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4- 1.1.12.11 Window Subclassing Functions 



WinSubclass Window 



Format 



FARPROC WinSubclassWindow (hwnd, lpfnNewWindowProc) 
HWND hwnd; 

FARPROC lpfnNewWindowProc; 

Description 

This function is used to subclass the specified win- 
dow. The window procedure of the specified win- 
dow is replaced with lpfnNewWindowProc, which 
is a far procedure address of a window procedure. 

This function returns the specified window’s previ- 
ous window proc address. 

Note When subclassing, the new procedure address 

should call the old procedure address in place of 
calling WinDefWindowProcQ. 

To reverse the effect of subclassing, simply call 
WinSubclassWindowQ with the previous window 
procedure address. 

This routine does not allow the application to sub- 
class a window associated with another process. 

If this function fails, zero (LONG) is returned, 
ted 

typdef struct { 

ULONG styleClass; 

FARPROC lpfnWindowProc; 

I NT cbWndExtra; 

UINT idModule; 

> CLASSINFO; 



WinQuer yClassInfo 

Format 



BOOL WinQueryClassInfo (hab, IpszClassName, 
lpClassInfo) 

HAB hab; 

LPSTR IpszClassName; 

CLASSINFO FAR * lpClassInfo; 

Description 

This function is used to obtain information about 
the specified window class. Returns TRUE if the 
class named by *lpszClassName exists, FALSE 
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otherwise. If the class exists, information about 
the class is returned in *lpClassInfo. 

Notes This function is used to create subclasses of a 
given class. 



4-1.1.12.12 Window Enumeration Functions 

The three functions WinBeginEnumWindowsQ, WinEnumWindowQ, and 
WinEndEnumWindowsQ are used to enumerate windows that might be 
owned by different processes or threads. Any one application can not 
make any assumptions about a window owned by another process or 
thread unless that window is locked. Instead of locking all the windows in 
the list to be enumerated, Presentation Manager makes a snapshot copy of 
the list of window handles to be enumerated, which is represented by an 
’enumeration’ handle. The application uses this handle for subsequent 
enumeration calls to get at the windows in this list. There is a final call 
which ends the enumeration and frees the enumeration handle. See "Win- 
dow Locking". 

Below is an example of how these functions are used to enumerate win- 
dows: 

/* 

* Enumerate all top level windows 
*/ 

hEnum = WinBeginEnumWindows (NULL) ; 

/* 

* For each window handle returned from WinEnumWindow () , call our 

* internal function DoSomething () , until we've enumerated the 

* entire list. 

*/ 

while ( (hwnd = WinEnumWindow (hEnum) ) != NULL) { 

DoSomething (hwnd) ; 

/* 

* Be sure to unlock the window when finished with it. 

*/ 

UnlockWindow (hwnd) ; 

> 

/* 

* Finish the enumeration 
*/ 

WinEndEnumWindows (hEnum) ; 

Window enumeration using these functions may be nested; however, a call 
to WinEndEnumWindowsQ must be made with the handle returned from 
its corresponding call to WinBeginEnumWindowsQ. 
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WinBeginEnumWindows 



Format 



HENUM WinBeginEnumWindows (hab, hwndParent) 
HWND hwndParent; 

HAB hab; 

Description 

This function begins the enumeration of all the 
children of hwndParent, returning a handle to be 
used when enumerating these windows. Regardless 
of any subsequent changes to the window Z order- 
ing, the windows are enumerated in the Z ordering 
that existed at the time WinBeginEnumWindows 
was called. This ensures that all of the child win- 
dows of hwndParent are enumerated. 

If hwndParent is NULL, all top level windows are 
enumerated. 

Windows may be destroyed after WinBe- 
ginEnumWindowsQ is called. 

See the example above. 



WinEnumWindow 



Format 



HWND WinEnumWindow (hEnum) 

HENUM hEnum; 

Description 

This function returns the next window to be 
enumerated. hEnum is a handle returned by Win- 
BeginEnumWindowsQ. Each call to this function 
returns the next window to be enumerated. NULL 
indicates that all windows have been enumerated. 

WinEnumWindow() always returns a locked win- 
dow handle, which must be unlocked by the caller. 

See example above. 



WinEndEnumWindows 



Format 



BOOL WinEndEnumWindows (hEnum) 
HENUM hEnum; 
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Description 

This function ends the enumeration of the win- 
dows. hEnum is the handle returned by a previous 
call to WinBeginEnumWindows(). 

See example above. 



4- 1.1. 12. 13 Window Hit Testing 

"Hit Testing" refers to the process of determining what object a mouse 
point is in. Window hit testing is the process of determining which win- 
dow a given mouse point is within. 



Win WindowF romPoint 



Format 



HWND WinWindowFromPoint (hab, hwndParent, 
lppt , fEnumChildren) 

HAB hab; 

HWND hwndParent; 

POINT FAR * lppt ; 

BOOL f EnumChil dren ; 

Description 

Returns the window handle underneath the 
specified point, by checking to see if *lppt is within 
the window rectangles of the children of 
hwndParent. Returns hwndParent if the point is 
not inside any of the children of hwndParent, but 
is inside hwndParent. Returns NULL if the point 
is outside hwndParent. 

*lppt must be specified in window coordinates, 
relative to hwndParent. 

If hwndParent is NULL, then all top level windows 
are enumerated. In this case, *lppt must be rela- 
tive to the top left corner of the screen. 

If fEnumChildren is TRUE, all descendants of 
hwndParent are hit tested; otherwise, only 
immediate children of hwndParent are hit tested. 
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4-1.1. 12. 14 Coordinate Mapping 



WinMapWindowPoints 



Format 



void WinMapWindowPoints (hab, hwndFrom, hwndTo, 
lprgpt, cpt) 

HAB hab; 

HWND hwndFrom; 

HWND hwndTo ; 

POINT FAR * lprgpt; 

I NT cpt; 

Description 

Maps hwndFrom relative window coordinate 
points to hwndTo relative window coordinate 
points, lprgpt is a far pointer to an array of 
POINT structures to map, and cpt is the number 
of structures in the array. 

If hwndFrom is NULL, the points in the array are 
assumed to be in screen coordinates. 

If hwndTo is NULL, the points in the array will be 
mapped to screen coordinates. 

lprgpt may be used to point to a RECT structure; 
in this case cpt must be 2. 

Examples 



/* map from window to screen coordinates */ 
WinMapWindowPoints (hwndFrom, NULL, lppt, cpt) ; 

/* map from screen to window coordinates */ 
WinMapWindowPoints (NULL, hwndTo, lppt, cpt); 

/* map from child to parent window coordinates */ 
WinMapWindowPoints (hwndChild, 

WinQuery Window (hwndChild, QW_PARENT, FALSE), 
lppt, cpt) ; 



4-1.1.12.15 Accessing Window Words 

For window classes registered by applications, it is possible to reserve 
extra memory for each window that can be used by the window procedure 
to store any extra information that may be required for the window class. 

When a window class is registered, the number of extra bytes to reserve is 
specified. Every window instance of that class will have these bytes allo- 
cated and initialized to 0, which can be read and written by the applica- 
tion or window procedure. 
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These functions are used to access this reserved memory. In addition, 
there are special values that can be used to access certain internal window 
fields, as shown in the table below. QWI_ constants are for use with Win- 
Query WindowUInt() and WinSetWindowUIntQ, and QWL_ constants are 
for use with WinQueryWindowULongQ and WinSetWindowULongQ: 



Standard WinQueryWindowUInt Indexes 
Index 

QWL_HMQ 

Message queue handle 

QWI_ID 

Window ID (ID passed to WinCreateWindowQ) 

QWL_ STYLE 

Window style 

QWL_ WNDPROC 

Window Procedure address 

QWL_ USER 

The following preregistered window classes have a window 
ULONG at WinSet/QueryWindowULongQ offset 
QWL-USER available for application use: 

— WC_ DIALOG 

— WC_ FRAME 

— WC_ LISTBOX 

— WC_ BUTTON 

— WC_ STATIC 

— WC-EDIT 

— WC_ SCROLLBAR 

— WC-MENU 

This is useful for placing application-specific data in con- 
trols. 

Note: QWI_ constants should NEVER be used with WinQueryWindowU- 
Long() or WinSetWindowULongQ, and QWL_ constants should NEVER 
be used with WinQueryWindowUIntQ or WinSetWindowUIntQ. 



WinQueryWindowUInt 



Format 

UINT WinQueryWindowUInt (hwnd, ib) 
HWND hwnd; 
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I NT ib; 



WinSetWindowUInt 


Format 


UINT WinSetWindowUInt (hwnd, ib, w) 
HWND hwnd;. 

I NT ib; 

UINT w; 


Descript 


ion 

These functions are used to read or write 16 bits of 
information in the reserved window word memory 
associated with the specified window, at index ib. 
ib may also be one of the QWI_ values shown in 
the table above. 




ib is a zero-based index into the window words. 
Only values between 0 and cbWndExtra may be 
used, or any of the QWI_ values shown in the 
table above. 




WinQueryWindowUInt() returns the unsigned 2 
byte integer at the index specified by ib. Win- 
SetWindowUIntQ stores the unsigned 2 byte 
integer w at the index specified by ib, and returns 
the previous contents of the ulnt. 




These functions are used to read the window words 
associated with the specified window, using the 
index ib. ib may also be one of the QWI_ values 
in the table above. 


Notes 


The QWL_ constants may not be used with these 
functions. 


WinQueryWindowULong 


Format 


LONG WinQueryWindowULong (hwnd, ib) 
HWND hwnd; 

I NT ib; 



WinSetW indowULong 

Format 



LONG WinSetWindowULong (hwnd, ib, IData) 
HWND hwnd; 
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I NT ib; 

ULONG IData; 

Description 

These functions are used to read or write 32 bits of 
information in the reserved window word memory 
associated with the specified window, at index ib. 
ib may also be one of the QWL_ values shown in 
the table above. 

ib is a zero-based index into the window words. 
Only values between 0 and cbWndExtra may be 
used, or any of the QWL_ values shown in the 
table above. 

WinQueryWindowULongQ returns the long at the 
index specified by ib. WinSetWindowULongQ 
stores the long IData at the index specified by ib, 
and returns the previous contents of the long. 

Notes The QWI_ constants may not be used with these 
functions. 



4-1.1.12.16 Active Window Routines 



WinSetActiveWindow 



Format 



BOOL WinSetActiveWindow (hab, hwnd) 

HWND hwnd; 

HAB hab; 

Description 

This function is used to set the active window to 
the specified window. Returns TRUE if successful, 
FALSE otherwise. 

Notes This function sets the keyboard focus to NULL, 

and does not directly set the focus. Typically, the 
focus is set during the processing of the 
WM_ ACTIVATE message by the window being 
activated. 

WinSetActiveWindowQ should not be called unless 
it is directly or indirectly a result of user input. 

WinSetActiveWindow() succeeds only in the fol- 
lowing conditions: 

1. It is being called in the context of the thread 
that is currently associated with the active 
application. 
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2. It is being called in the context of a thread that 
is currently processing a message from another 
application. See WinInSendMsg(). 

3. It is being called when an application is being 
started. 

Messages may be recieved from other processes or 
threads if either the current active window or the 
new active window is associated with another 
thread or process. 

The following messages are sent by SetActive Win- 
dow. No messages are sent if hwnd is the same as 
the current active window: 



Message 

When Sent 
WM_ ACTIVATE 

This message is sent first to the window 
being deactivated with 
LOUINT(lParaml) == FALSE. Then, 
this message is sent to the window being 
activated with LOUINT(lParaml) == 
TRUE and HIUINT(lParaml) == 
TRUE. 

Note that a WM_SETFOCUS message is sent to 
the window which is losing the focus (if any). 

During the processing of a WinSetActiveWindow() 
call, if WinGetActiveWindow or WinGetFocus() 
are called, the old active and focus windows are 
returned until the new ones have been established. 
In other words, even though 
WM_ ACTIVATE(false) messages may have been 
sent to the old windows, those old windows are 
considered to be active and have the focus (until 
the system establishes the new active and focus 
windows). 



WinGetActiveWindow 



Format 



HWND WinGetActiveWindow (hab, fLock) 

HAB hab; 

BOOL fLock; 

Description 

This function returns the current active window, 
or NULL if there is no active window. If fLock is 
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TRUE, then the window is returned locked, and 
the caller is responsible for unlocking it. If fLock is 
FALSE, the window is returned unlocked. See 
"Window Locking" 



WM_ ACTIVATE 



Format 



WM_ACT I VATE 

LOUINT (lparaml) : BOOL f Active; 

HIUINT (lParaml) : BOOL fSetFocus; 
lparam2 : HWND hwndActive; 

Returns : BOOL fProcessed; 

Description 

This message is sent by WinSetActiveWindowQ, 
WinSetFocusQ, WinCreateWindow(), 
WinShowWindow(), WinSetWindowPosQ, or Win- 
SetMultWindowPosQ when a window is activated 
or deactivated. If LOUINT(lParaml) is TRUE, the 
window is being activated; if FALSE, the window 
is being deactivated. 

When LOUINT(lParaml) is FALSE, an application 
should save away the current focus window, for 
later restore when the window is reactivated. 
lParam2 has the window handle of the window 
being activated. 

When LOUINT(lParaml) is TRUE and 
HIUINT(lParaml) is TRUE, the application should 
set the focus to tne saved focus window. If 
HIUINT(lParaml) is FALSE, the message is being 
sent as a result of a WinSetFocusQ call, therefore 
the application should NOT set tne focus. 
lParam2 has the window handle of the window 
being deactivated. 

The default WinDefWindowProcQ behaviour is to 
simply set the focus to the window being activated 
if LOUINT(lParaml) and HIUINT(lParaml) are 
both TRUE. WinDefWindowProcQ does nothing 
otherwise. 

Notes WM_ ACTIVATE with LOUINT( lParaml) == 

FALSE is sent before WM_ ACTIVATE with 
LOUINTHParaml) == TRUE. Any 
WM—SETFOCUS messages with lparam2 == 
FALSE are sent BEFORE the deactivation mes- 
sage. WM_SETFOCUS messages with lparam2 
== TRUE are sent AFTER the activation 
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message. 

If WinSetFocus() is called during WM_ ACTIVATE 
or WM-ACTIVATETHREAD message processing, 
a WM-SETFOCUS message with fFocus == 
FALSE is not 

Except in the case of the WM_ ACTIVATE mes- 
sage with fActive == TRUE, an application pro- 
cessing WM_SETFOCUS, WM_ ACTIVATE, or 
WM_ ACTIVATETHREAD should not change the 
focus window or active window. If it does, focus 
and active window must be restored before the 
application returns from processing the message. 
For this reason, any dialog boxes or windows 
brought up during WM—SETFOCUS, 

WM_ ACTIVATE or WM_ ACTI VATETHREAD 
processing should be system modal. 



WM_ ACTIVATETHREAD 



Format 



WM_ACT I VATETHREAD 

lParaml: BOOL fActive: 

LOUINT (lParam2) : UINT idProcess; 

HIUINT (lParam2) : UINT idThread; 

Returns : OL 

Description 

This message is sent by the WinSetActivwindow(), 
WinSetF ocus(), WinCreateWindowQ, 
WinShowWindow(), WinSetWindowPos(), or Win- 
SetMultWindowPos() functions when a window is 
being activated or deactivated, and the 
process/thread that owns the window being 
activated is different to the process/thread that 
owns the current active window. 

• If lParaml == TRUE, the window is being 
activated, and lparam2 identifies the 
process/thread associated with the window 
that was the previous active window, or NULL 
if there was no previous active window. 

• If lParaml = False, the window is being 
deactivated, and lparam2 identifies the 
process/thread associated with the window 
that will become the new active window, or 
NULL if there will be no active window. 
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WinlsThreadActive 



Format 



BOOL WinlsThreadActive (hab) 

HAB hab; 

Description 

This function returns TRUE if the active window 
is associated with the current thread. 



4-1.1.12.17 Window Flashing 



WinFlashWindow 



Format 



BOOL WinFlashWindow (hwnd, fFlash) 

HWND hwnd; 

BOOL fFlash; 

Description 

This function is used to start or stop window flash- 
ing. If fFlash is TRUE, window flashing is begin; if 
fFlash is FALSE it is stopped. Returns TRUE if 
successful, FALSE otherwise. 

A window is normally flashed by inverting the 
state of the title bar. A beep is emitted for the 
first 5 flashes. 

Notes This function is used when it is necessary to bring 
up a dialog box or message box when the applica- 
tion is not the current application. The flashing 
window indicates that the user’s attention is 
required -- when the user activates the window, the 
flashing stops and the message box or dialog box is 
brought up. 



4- 1.1. 12. 18 System Modal Window Routines 

The "System Modal Window" is a special top level window that recieves 
all mouse and keyboard input. Input may also routed to one of its chil- 
dren. All other top level windows behave as if they are disabled; no 
interaction is possible. 
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If another window is explicitly set to the active window, the newly 
activated window is set to the system modal window. The previous system 
modal window may no longer be interacted with. If a system modal win- 
dow is destroyed, the window activated as a result becomes the system 
modal window. 

Non-system modal windows are not actually disabled with WinEnableWin- 
dow(); they are simply made non-interactive. No messages are sent, and 
the WS_ DISABLE style bits are not changed. 



WinGetSysModal Window 



Format 



HWND WinGetSysModalWindow (hab, fLock) 
HAB hab; 

BOOL fLock; 

Description 

This function returns the window handle of the 
current system modal window, NULL if there is 
none. If fLock is TRUE, then the window is 
returned locked, and the caller is responsible for 
unlocking it. If fLock is FALSE, the window is 
returned unlocked. See "Window Locking" 



WinSetSysModal Window 



Format 



HWND WinSetSysModalWindow (hab, hwnd) 

HWND hwnd; 

HAB hab; 

Description 

This function sets the current system modal win- 
dow to hwnd, and returns the previous system 
modal window handle. The window handle is 
returned unlocked. 

If hwnd is NULL (i.e., there is no system modal 
window), other windows receive mouse input again 
as usual. 
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4.1.2 Window Drawing Management Architecture 



4. 1.2.1 The Window DC 

Graphical output to a window is done to a Presentation Space, like any 
other graphics output. However, in order to draw in a window, the PS 
must be associated with a special kind of device context (DC) called a 
"Window DC". A window DC may be created for a window, and it is 
automatically destroyed when its associated window is destroyed. 

As explained earlier in the section on "Window Management", not all of a 
window is necessarily visible on the screen; a window may be obscured by 
windows above, and clipped to its parent. The window DC associated 
with a window allows access only to the part of the screen that 
corresponds to the part of the window that is actually visible. 

The area of a window that is actually visible is called the "visible region", 
or "visrgn" for short. This visrgn is part of a window DC, and is always 
maintained by the window manager as windows are rearranged. It cannot 
be changed by the application. All output to a PS attached to a window 
DC is clipped to the visrgn of the window DC. The origin of the PS is 
always the bottom left corner of the window rectangle, regardless of where 
it is located on the screen. 

This visrgn clipping does not affect the normal GPI clipping. An applica- 
tion is free to change the PS clipping area as it wishes. Physically, how- 
ever, output is clipped to the intersection of the PS clipping area and the 
window DC visrgn. 

Getting ready to draw into a window requires three steps: 

1. Create a window 

2. Create a PS 

3. Create a window DC for the window created above. 

4. Associate the window DC with the PS. Now, any drawing to the 
PS will be drawn in the visible part of the window. 

These steps are very similar to those required for drawing on any other 
graphical device. 

If you want to use a micro-PS instead of a standard PS in order to save 
memory, here’s what you have to do: 

1. Create a window 

2. Create a window DC for the window created above 
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3. Create a micro-PS from the window DC created above. 



4. 1.2. 2 Cached Micro-PS 

There is another way that an application may obtain a micro-PS for use in 
drawing in a window, that does not require the creation of a window DC 
or PS. 

The window manager maintains a cache of micro-PSs and window DCs 
that an application may use. To obtain a micro-PS, the function 
WinGetPS() is called with the window to be drawn in. The micro-PS 
obtained from the cache is associated with a window DC for the specified 
window. 

In order to allow other applications access to the cache, the micro-PS must 
be released by calling WinReleasePS() when it is no longer required. 

When a micro-PS is obtained from the cache, its state (colors, transforms, 
clipping state, etc) is the same when a PS is first created. Any state 
changes made to a cached PS are lost when it is released. The origin of 
the PS is always aligned with the window rectangle. 

There are two key advantages to using a cached PS: space and speed. 

A normal PS occupies about IK of memory. A window DC occupies about 
400 bytes. Creating a PS and an DC takes a fair amount of execution 
time, as well. 

Cached PSs do not require any additional memory. Obtaining and releas- 
ing a PS from the cache is much faster than creating and destroying a PS 
and a window DC. 

These considerations are especially important with some windows, such as 
dialog boxes, that may contain 20 or 30 child windows. If each of those 
windows had its own PS and window DC, some 30K to 45K of memory 
would be occupied by all the PS’s and DC’s. 



4. 1.2. 3 Application PS vs. Cache PS Considerations 

Application PSs are appropriate when a window stays around for a long 
period, such as with main application windows. They should also be used 
if non- retained graphics are being used, or if any of the features of a PS 
not available with micro-PSs is desired. 

Application PSs are faster, if windows are not being created and des- 
troyed. They are also useful if there are lots of PS state changes required, 
or a normal (non-micro-) PS is required. Visrgn calculation takes place 
after each window management operation, though. They also take 
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memory. 

Cached PSs are faster if windows are being created and destroyed often. 
Getting a cache entry the first time causes a region calculation; subsequent 
calls are cheap. Since state is lost when a cached PS is released, it is some- 
times expensive to have to select state in every time a PS is obtained. 



4. 1.2. 4 Window Clipping Options 

An application has some control over how windows are clipped. There are 
two window style bits and a class style bit that control window clipping. 
These styles control: 

1. Whether a window excludes the area of its children 

2. Whether a window excludes the area of its siblings above 

3. Whether a window is clipped to the window rectangle, or to its 
parent’s visrgn. 

A window may be created with one or both of the following window or 
class styles to change the clipping behavior: 



Window/Class Style 
Behavior 

WS-CLIPCHILDREN 

The area of a window’s children is excluded from the win- 
dow. If this style is not specified, the children are not 
excluded. 

WS-CLIPSIBLINGS 

The area of a window’s siblings above the window is 
excluded from the window. If this style is not specified, the 
siblings are not excluded. 

CS-PARENTCLIP 

The parent’s visrgn is used for clipping. The origin of the PS 
is still the bottom left corner of the window, but drawing 
may be done outside of the window rectangle. Output is 
clipped to the visible region of the parent. The children of 
the parent are not excluded, even if the parent has the 
WS_ CLIPCHILDREN style. If this class style is not 
specified, the window is clipped to its window rectangle. 
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4. 1.2. 5 Window Clipping Considerations 

The key reason for allowing these clipping options is speed. It takes a cer- 
tain time to perform the clipping region calculations that are required. 

For cached PSs, these calculations are performed if there are no valid 
cache entries for the window. A cache entry is invalidated from the cache 
any time window rearrangment, hiding, or showing is done that might 
affect the visrgn of the window. When a cached micro-PS is returned by 
WinGetPSQ, it is considered to be "in use" until it is released with Win- 
ReleasePSQ. Cache entries that are not in use may also be reused for other 
windows as required. 

For windows with permanent window DCs, these calculations are per- 
formed every time the window visible region changes as a result of any 
window rearrangement, hiding, or showing that affects the visrgn of the 
window. 



Style Recommendation 

WS-CLIPCHILDREN 

The WS_CLIPCHILDREN style should only be used if it is 
necessary to prevent a parent window from drawing on its 
children. If both the parent and the child are invalidated at 
once, the painting order will be top down; the parent will 
draw before the child draws. If the child is invalidated 
independently of the parent, the child will draw indepen- 
dently of the parent. 

WS-CLIPSIBLINGS 

WS-CLIPSIBLINGS should generally be used when child 
windows physically overlap. Sometimes it may be avoided 
even if they do overlap: since sibling windows are always 
repainted in front to back order, the image on the screen 
may be deterministic. 

CS_ PARENTCLIP 

The CS_ PARENTCLIP style is normally used by non- 
overlapping windows with a common parent. All windows 
with CS-PARENCLIP and having the same parent window 
will use the same visrgn, and therefore the same origin- 
modified PS for drawing. This avoids subsequent visrgn cal- 
culations for each window, a drawing speed gain. It makes no 
sense for a CS_ PARENTCLIP window to have either the 
WS_ CLIPCHILDREN or WS-CLIPSIBLINGS styles defined, 
as they defeat the purpose of the CS_PARENTCLIP style. 
Most of the standard controls are CS_ PARENTCLIP win- 
dows, and none of them draw outside their window rectan- 
gle. Generally a CS_ PARENTCLIP window should not draw 
outside its window rectangle. 
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4. 1.2. 6 Application PS Example 

Application initialization: 



hwnd = WinCreateWindow (...); 
hps = GpiCreatePS (...); 

hdcWindow = WinOpenWindowDC (hwnd) ; 

hdcPrinter = GpiCreateDC ("Printer") ; 

GpiAssocDC (hps , hdcWindow) ; 
DrawDocument (hps) ; 



/* 


Create a 


window 






*/ 


/* 


Create a 


PS 


for 


graphics 


*/ 


/* 


Create a 


DC 


for 


output 


to 


*/ 


/* 


window 










*/ 


/* 


Create a 


DC 


for 


output 


to 


*/ 


/* 


printer 










*/ 


/* 


Send output 


to 


screen 




*/ 


/* 


window 










*/ 


/* 


Draw the 


document 




*/ 



WM_ PAINT message processing: 

WinBeginPaint (hwnd, hps, (LPRECT) &rcPaint) ; 



DrawDocument (hps) ; 


/* 


Redraw the document 


*/ 


WinEndPaint (hps) ; 








Printing: 








GpiAssocDC (hps, hdcPrinter) 


/* 


Send output to printer 


*/ 


DrawDocument (hps) ; 


/* 


Draw the document 


*/ 


4. 1.2. 7 Cached-PS Example 








hwnd = WinCreateWindow (...); 


/* 


Create a window 


*/ 


hps = WinGetPS (hwnd) ; 


/* 


Get cache PS for drawing 


*/ 


DrawDocument (hps) ; 


/* 


Draw the document 


*/ 


WinReleasePS (hps) ; 


/* 


Release the cache PS 


*/ 


WM_ PAINT message processing: 








hps = WinBeginPaint (hwnd, NULL, 


(LPRECT) SrcPaint) ; 




DrawDocument (hps) ; 


/* 


Redraw the document 


*/ 



WinEndPaint (hps) ; 
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4. 1.2. 8 Window Repainting after Window Rearrangment 

When windows are rearranged or shown and a new area of the window is 
made visible, it is the responsibility of the window procedure to redraw the 
image in the area of the window that has been uncovered. This update 
repainting may be done synchronously at the time the rearrangement 
takes place, or asynchronously some time after the rearrangement opera- 
tion, when an application chooses to redraw the window. The 
CS-SYNCPAINT style bit controls whether a window is updated synchro- 
nously or asynchronously. 



4- 1.2. 8.1 Asynchronous Window Updating 

When some part of a window not having CS_SYNCPAINT style is made 
visible due to window rearrangment or showing of the window, the window 
is not painted right away. Instead, the area to be updated is saved in the 
window’s "Update Region". The update region is the area of a window 
that will eventually require repainting. As subsequent areas are made visi- 
ble due to additional window rearrangement, these areas are accumulated 
(added) to the window’s update region. 

Accumulating an area into the update region is called "Window Invalida- 
tion". Removing area from the update region is called "Window Valida- 
tion". In to the invalidation and validation that occurs as a result of win- 
dow rearrangement, An application can explicitly invalidate and validate 
areas of a window. 

When an application calls WinGetMsg() or WinPeekMsg() and there are no 
other messages in the queue, if there are any windows associated with the 
current queue that require updating (non-empty update regions), a 
WM_ PAINT message is returned for that window. The WM_ PAINT mes- 
sage is not actually placed in the application queue; they are returned only 
as often as WinGetMsgQ or WinPeekMsg() is called. Since multiple invali- 
dations are accumulated into the single update region, a single 
WM_ PAINT message may be generated as a result of more than one 
invalidation. 

WM_ PAINT messages are always generated in a top-down fashion: first 
the parent, then its children, etc. 

If necessary, an application may ensure that an async paint window has 
been updated by calling the UpdateWindowQ function. If the window has 
an update region, a WM_ PAINT message is sent to the window procedure. 
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4- 1.2. 8. 2 WM— PAINT Message Processing 

The WM_ PAINT message is processed by calling the WinBeginPaint() 
function. The WinBeginPaintQ function returns a PS handle that is asso- 
ciated with a window DC with a visible region set to the intersection of 
the window’s visible area and its update region: this is the area that must 
be updated. All drawing to the PS will only be done in those areas that 
require updating. 

If the window is using a cached PS, then the returned PS handle is from 
the cache. If a window DC was created for the window, the PS handle to 
use for updating is passed as a parameter to BeginPaint. 

With the PS handle, the window procedure must simply redraw the con- 
tents of the window. Since the PS is clipped to the update region, only the 
part of the window that needs to be updated is redrawn. 

The rcPaint rectangle is the bounding rectangle (in window coordinates) of 
the area that must be updated. This rectangle can be used to minimize 
the amount of redrawing that must be done. 

After the window has been repainted, WinEndPaintQ is called to restore 
the visible region of the window DC to its previous state. If the PS handle 
is a cached PS, then the PS is released by WinEndPaintQ. 



4 .1.2. 8. 8 Incremental Window Updating 

It is sometimes useful to update an async paint window incrementally one 
part at a time. The idea is that multiple WM_ PAINT messages are 
required to repaint the entire window. This is especially useful with win- 
dows that paint slowly: after processing each WM_ PAINT message, exe- 
cution returns back to the application’s main loop, where user input can 
be processed if it has occured. 

This can be accomplished by calling either WinGetUpdateRectQ or 
WinGetUpdateRgnQ to obtain a rectangle or region that describes the 
area that needs updating. These calls do not remove the window’s update 
region. Based on this information, a part of the window can be updated, 
and validated with WinValidateRgnQ or WinValidateRectQ. 



4. 1.2. 9 Synchronous Window Updating 

If a window rearrangmenent or window showing or hiding operation 
occurs, any affected windows with the CS-SYNCPAINT style are updated 
before the operation is completed. Windows with the CS-SYNCPAINT 
style are called "Sync Paint" window's. 
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Sync paint windows are usually painted as soon as they are invalidated. If 
the sync paint window has an async parent that isn’t 
WS_ CLIP CHILDREN and they both get invalidated by a single invalida- 
tion, the painting of its sync paint children is deferred until the async 
parent processes the WM_ PAINT message, so that the correct drawing 
order (top-down, parent-child) is maintained. 

These messages are also send as a result of calls to WinlnvalidateRectQ or 
WinlnvalidateRgnQ, and WinEndPaintQ. 



4.1.2.10 Synchronous vs. Asynchronous Painting 

Synchronous painting windows are well suited when a window can (or 
must) be drawn very quickly, as is the case with the controls that make up 
a window frame or a dialog box. Sync paint windows must draw quickly 
because the operation that is causing the WM_ PAINT message will not 
complete unti 1 the message has been processed. 

Asynchronous painting is appropriate for windows that are relatively slow 
to be redrawn. By putting off redrawing until there is less activity, the 
system will keep up with a user that types or uses the mouse quickly. This 
feature can prevent the swapping in and out of application code as well. 

Generally, asynchronous painting is used for main application windows. 

4.1.3 Window Drawing F unctions 

This sections documents the calls mentioned above plus several drawing 
helpers. It is assumed that you’ve read the overview above. 



WinGetPS 



Format 



HPS WinGetPS (hab, hwnd) 

HWND hwnd; 

HAB hab; 

Description 

This function returns a PS handle that can be used 
for drawing in the specified window. The returned 
PS is a "micro-PS"; not all GPI calls may be made. 
The initial state of the PS is the same as the initial 
state of a PS created with GpiCreatePSQ. 

The visible region of the returned PS depends on 
the existence of the following window and class 
styles: 
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Style Description 

WS-CLIPCHILDREN 

All of the window’s children are 
excluded. 

WS-CLIPSIBLINGS 

All siblings above the window are 
excluded. 

CS-PARENTCLIP 

The visrgn is the same as the window’s 
parent. The PS origin and pattern draw- 
ing origin is established normally. 

This style optimizes the use of the PS 
cache by minimizing the visrgn calcula- 
tion required for child windows. 



WinReleasePS 



Format 



BOOL WinReleasePS (hps) 

HPS hps; 

Description 

This function returns a PS handle obtained with 
WinGetPSQ to the cache. Returns TRUE if suc- 
cessful, FALSE otherwise. 

See section on "Cached PS’s" at the beginning of 
this section. 



WinOpenWindowDC 

Format 



HDC WinOpenWindowDC (hwnd) 

HWND hwnd; 

Description 

Opens a window DC associated with the specified 
window handle that may be used with Gpi- 
CreatePS() or GpiAssocDCQ in order to obtain a 
PS to draw in the window. Returns NULL if 
unsuccessful. 

Notes The window DC is automatically destroyed when 
its associated window is destroyed. The returned 
DC handle must NOT be destroyed with 
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GpiDestroyDC(). 

The visrgn of the DC is updated automatically as 
windows are rearranged. 

Only one window DC per window may be created. 



WinBeginPaint 



Format 



HPS WinBeginPaint (hwnd, hps, IprcPaint) 
HWND hwnd; 

HANDLE hps; 

LPRECT IprcPaint; 

Description 

This function is called during the processing of the 
WM_ PAINT message in order to obtain a PS han- 
dle with a visible region corresponding to the area 
of the window that should be repainted. 

If hps is NULL, one is obtained for use from the PS 
cache. Otherwise, the window DC associated with 
hwnd is selected into hps, and hps is returned. 

If IprcPaint is not equal to NULL, this function 
also fills in the rectangle pointed to be IprcPaint 
with the rectangle bounding the window area need- 
ing updating, in window coordinates (regardless of 
the transform of the hps). 

Notes The update region associated with hwnd is 
removed; i.e., the entire window is validated. 

WinBeginPaint() hides the caret if it is flashing in 
hwnd, and later shows it again in WinEndPaintQ, 
which must be called once the application is 
finished drawing. 

See "Asynchronous Window Updating" at the 
beginning of this section. 



WinEndPaint 



Format 



void WinEndPaint (hps) 

HPS hps; 

Description 

This function is used at the end of WM_ PAINT 
message processing to restore the PS used for 
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repainting to its original state, and to update the 
invalid sync paint windows of hwnd. 

If the PS used for repainting was associated with a 
different DC handle than the window DC selected 
by WinBeginPaintQ, the previous DC handle is 
reassociated with the PS. 

If the caret was hidden by WinBeginPaintQ, the 
caret is shown again. 

Note that if the window for which the WinBegin- 
PaintQ / WinEndPaintQ sequence is done has some 
Synch Paint children, these are automatically 
updated by the WinEndPaint call. 

See "WinBeginPaintQ" above and "Asynchronous 
Window Updating" at the beginning of this sec- 
tion. 



WinlnvalidateRect 



Format 



BOOL WinlnvalidateRect (hab, hwnd, lprc) 
HWND hwnd; 

LPRECT lprc ; 

HAB hab; 



WinlnvalidateRgn 

Format 



BOOL WinlnvalidateRgn (hab, hwnd, hrgn) 

HWND hwnd; 

HRGN hrgn; 

HAB hab; 

Description 

If the specified window is an asynchronously 
painted window, These function adds a rectangle 
or a region to the specified window’s update 
region. If either lprc or hrgn is NULL, the entire 
window is invalidated. 

If the window is a CS-SYNCPAINT window, the 
window is repainted before WinlnvalidateRectQ 
returns. 

If the window is WS_ CLIPCHILDREN and invalid 
area overlaps some CS_SYNCPAINT children, 
those children will be repainted before Winlnvali- 
dateRectQ returns. 
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If hwnd is NULL, area of of the screen (the desktop 
window) is invalidated. In this case, if lprc or hrgn 
is NULL, the entire screen is invalidated. 

These functions return TRUE if successful, FALSE 
otherwise. 

See "Asynchronous Window Updating" for more 
information. 



WinValidateRect 


Format 


BOOL WinValidateRect (hab, hwnd, lprc) 
HWND hwnd; 

LPRECT lprc; 

HAB hab; 


WinValidateRgn 


Format 


BOOL WinValidateRgn (hab, hwnd, hrgn) 
HWND hwnd; 

HRGN hrgn; 

HAB hab; 


Description 

These functions subtracts a rectangle or region 
from the specified window’s update region. This 
function is only used with async update windows. 




These functions have no effect on a window if any 
part of the window has been invalidated (such as 
as a result of another thread’s window rearrange- 
ment) since the last time WinBeginPaintQ, 
WinGletUpdateRect(), or WinGetUpdateRgn() was 
called. 




These functions return TRUE if successful, FALSE 
otherwise. 




See "Asynchronous Window Updating" for more 
information. 



Wi n Quer y UpdateRect 



Format 



BOOL WinQueryUpdateRect (hwnd, lprc) 
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HWND hwnd; 

LPRECT lprc ; 

Description 

This function returns the rectangle that bounds 
the update region of hwnd. This routine is usually 
used as an alternate to WinBeginPaintQ and 
WinEndPaint(), in incremental updating schemes. 
Typically the application calls WinQueryUp- 
dateRectQ to see what part of hwnd needs updat- 
ing, updates it, then calls WinValidateRectQ or 
WinValidateRgnQ to subtract that updated part 
from the update region. FALSE is returned if hwnd 
is totally valid ^no update region), lprc points to a 
buffer that receives the update rectangle in window 
coordinates. 

See "Asynchronous Incremental Updating" for 
more information. 



WinQueryUpdateRgn 



Format 



INT WinQueryUpdateRgn (hwnd , hrgn) 

HWND hwnd; 

HRGN hrgn; 

Description 

This function copies hwnd’s update region into the 
already existing region passed in, hrgn. This rou- 
tine is usually used as an alternate to WinBegin- 
PaintQ and WinEndPaintQ, in incremental updat- 
ing schemes. Typically the application calls Win- 
QueryUpdateRgnQ to see what part of hwnd needs 
updating, updates it, then calls WinValidateRectQ 
or WinValidateRgnQ to subtract that updated 
part from the update region. A code indicating the 
type of the region is returned, as for GpiCom- 
bineRegion. 

The application can select hrgn into a ps as the 
clip region and have drawing clipped to the 
window’s update region. 

See "Asynchronous Incremental Updating" for 
more information. 



WinUpdateWindow 
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Format 



BOOL WinUpdateWindow (hwnd) 

HWND hwnd; 

Description 

This function forces the updating of a window and 
its children. If hwnd is an async window, it and 
only its async children are updated. They get sent 
WM_ PAINT messages from within WinUp- 
dateWindowQ. If hwnd is a sync window, it and 
only its sync children are updated. They get sent 
WM_ PAINT messages from within WinUp- 
dateWindowQ. 

If hwnd is a child of a non-clip children parent, 
hwnd’s update region is subtracted from the 
update region of the parent, if the parent has one. 
This is so the parent, who will be drawing after 
hwnd, will not draw on top of what hwnd draws. 

If the window was updated, this function returns 
TRUE, otherwise FALSE. 

See "Visrgn Calculation" at the beginning of this 
section. 



WinExcludeUpdateRgn 



Format 



INT WinExcludeUpdateRgn (hps, hwnd) 

HPS hps; 

HWND hwnd; 

Description 

This function subtracts the update region for hwnd 
(if one exists) from the visrgn of hps. This is used 
to prevent the application from drawing in areas of 
hwnd which are already invalid. 

A code indicating the type of clipping area is 
returned, as for GpiCombineRegion. 

Notes This function is typically used in situations to 

avoid drawing in a window when it is likely most 
of the window is invalid, such as when replacing a 
selection when a window recieves a 
WM_ SETFOCUS message. 
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WM_ PAINT 



Format 



WM_PAINT 
lParaml: 0 
lParam2: OL 

Description 

This message is sent to asynchronously updated 
windows whenever Presentation Manager o r an 
application makes a request to repaint a window’s 
invalid bits. This message is either sent from 
WinUpdateWindowQ when the application makes 
this call, or is returned from WinGetMsgQ. In 
either case, the application only receives the mes- 
sage if the window has an update region. 

See "Asynchronous Window Updating" at the 
beginning of this section. 



WinLockScreen 



Format 



BOOL WinLockScreen (hab, fLock) 

HAB hab; 

BOOL fLock; 

Description 

WinLockScreenQ is design to start and stop all 
screen output. If fLock is TRUE, nothing outputs 
to the screen until WinLockScreenQ is called again 
with fLock FALSE. All the areas would have been 
drawn by applications while the screen is locked 
are remembered and updated once the screen is 
unlocked. 

This function is used by threads that want to draw 
on an area of the screen in which they have no con- 
trol. The user interface sizing and moving code 
uses WinLockScreenQ while sizing or moving a 
window. All threads still run while the screen is 
locked. 

This function does not prevent screen group 
switches (which may be required to handle a hard 
error.) If fLock is TRUE, this function always 
returns TRUE. If fLock is FALSE, this function 
returns TRUE if no screen group switch occurred, 
or if the screen is locked. Otherwise, returns 
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TRUE. 

Note: If one thread locks the screen, other threads 
that call LockScreenQ are blocked (although they 
can receive messages) until the first thread unlocks 
the screen. 



WinLockVisRgns 



Format 



INT WinLockVisRgns (hab, fLock) 

HAB hab; 

BOOL fLock; 

Description 

This function is called by a thread if it doesn’t 
want any visrgns changing while it performs an 
operation on the screen, like copying screen bits 
into a memory bitmap. This function will block 
any other thread that tries to alter visrgns. hile 
visrgns are locked, no messages should be sent, and 
no functions called that could send messages. 

If fLock is TRUE, all visrgns are locked. If fLock is 
FALSE, all visrgns are unlocked. 

More than one thread can concurrently lock 
visrgns. The system increments a lock count, each 
time an app makes a lock call, and decrements a 
count each time a thread makes an unlock call. 

The visrgns can not change unless the lock count is 
zero. 

This function returns the lock count that results 
from the call. 

Note An thread is not allowed to unlock visrgns if the 
corresponding lock was performed by another pro- 
cess. 



4. 1.3.1 Drawing Helpers 



WinScrollWindow 



Format 



void FAR WinScrol lWindow (hwnd, dx, dy, 

IprcScroll, IprcClip, hrgnUpdate, 
IprcUpdate, rgfsw) 

HWND hwnd; 
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int dx; 
int dy; 

LPRECT IprcScroll; 

LPRECT IprcClip; 

HRGN hrgnUpdate; 

LPRECT IprcUpdate; 

UINT rgfsw; 

Description 

This routine scrolls the rectangle defined by 
*lprcScroll in the window hwnd by dx units hor- 
izontally and dy units vertically. All coordinates 
must be in device units. 

If IprcScroll is NULL, the entire window will be 
scrolled. *lprcClip is a clip rectangle that clips the 
destination of the scroll. Any part of hwn d’s 
update region that maps to scrolled bits will be 
offset too. 

If not NULL, IprcUpdate is filled with the bound- 
ing region of the invali d bits uncovered by the 
scroll. If not NULL, hrgnUpdate is modified to hoi 
d the region uncovered by the scroll, in window 
coordinates. 

rgfsw is an array of bits, which may be OR’ed 
together: 



SW_ SCROLLCHILDREN 

All children falling within the intersec- 
tion of IprcScroll and IprcClip will be 
scrolled by dx and dy units. 

SW_ INVALID ATERGN 

The invalid region created as a result of 
the scroll will be added to update regions 
of those windows affected. This may 
result in the sending of WM_ PAINT 
messages to CS_ SYNCPAINT windows 
before WinScrollWindow() returns. 

WinScrollWindowQ returns a code indicating the 
type of invalid region created by the scroll, as 
retuned by GpiCombineRegion. Note: If hwnd is 
not a clip children window, the bits of any child 
falling inside the scrolled area will be scrolled too. 
If this is the case , WinScrollWindow() should 
be called with SW_ SCROLLCHILDREN. 

No thread should be moving bits around in its own 
window by a ny other method than by 

using WinScrollWindow(), due to the critical sec- 
tion nature of window update regions. 
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The fastest scrolling method is without 
SW_ SCROLLCHILDREN and 
SW_ INVALID ATERGN. If scrolling needs to 
repeat quickly, don’t incl ude the 
SW_ INVALID ATERGN flag, and just repaint the 
invalid area if th e invalid region is rectangu- 
lar, otherwise invalidate and update. 

If the scrolling does not happen often, include the 
SW_ INVALIDATERGN flag, and WinScrollWin- 
dow() will invalidate and update sync paint win- 
dows automatically before returning. 



WinDrawText 



Format 



INT WinDrawText (hps, lpchText, cchText, lprc / rgfCmd) 
HPS hps; 

LPSTR lpchText; 

INT cchText; 

LPRECT *lprc; 

UINT rgfCmd; 

Description 

This function draws a single line of formatted text 
in the rectangle specified by lprc. hps is a handle 
to a presentation space, lpchText is a far pointer 
to the character string to be drawn, cchText is the 
count of characters to be drawn, and rgfCmd is an 
array of flags specifying how to draw the text. 

This function returns the actual number of charac- 
ters drawn that fit completely within lprc. 

If cchText is 0, the string is assumed to be zero 
terminated, and its length is automatically calcu- 
lated by WinDrawTextQ. 

The text is drawn using the currently selected text 
color and background color in the presentation 
space given by hps. The output is clipped to the 
rectangle specified by lprc unless the DT_ NOCLIP 
command is used. 

If a carriage return or line feed character occurs in 
the string it is assumed to terminate the line, even 
if the line is shorter than cchText. 

rgfCmd may be any combination of the following 
values: 
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WinDrawTextQ Flags 
Flag 

DT-LEFT 

Left justify the text. 

DT_ CENTER 

Center the text. 

DT_ RIGHT 

Right justify the text. 

DT_ VCENTER 

Vertically center the text. 

DT_TOP 

Top justify the text. 

DT_ BOTTOM 

Bottom justify the text. 

DT_ HALFTONE 

Halftone the text display. 

DT_ MNEMONIC 

If a mmenomic prefix character is 
encountered, the next character is drawn 
with mnemonic emphasis. 

DT-GETEXTENT 

No drawing is performed; *lprc is 
changed to a rectangle that bounds the 
string if it were drawn with Win- 
DrawText(). 

DT-UINTBREAK 

Only words that fit completely within 
the supplied rectangle are drawn. Words 
are assumed to be separated by space 
characters. 

Text is always drawn in the current font. 



WinHalftoneBitmap 



Format 



BOOL WinHal ftoneBitmap (hps, hbm, hbr, xdst, 
ydst, cxdst, cydst, xsrc, ysrc) 

HPS hps; 

HBITMAP hbm; 

HBRUSH hbr; 

INT xdst, ydst, cxdst, cydst; 

I NT xsrc, ysrc; 
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Description 

Thus function outputs a halftoned bitmap at loca- 
tion xdst, ydst, with extents of cxdst and cydst in 
the presentation space hps. xsrc and ysrc specify 
the starting location within the bitmap. The back- 
ground of that location must be drawn first, as 
WinHalftoneBitmap() only draws the ’halftoned’ 
bits. 

The return value is TRUE if the operation was a 
success. 



WinDrawIcon 



Format 

BOOL WinDrawIcon (hps, x, y, hlcon, rgfHalftone) 
HPS hps; 

INT x, y; 

HI CON hlcon; 

UINT rgfHalftone; 

Description 

Where hps is handle to a presentation space, x and 
y are the coordinates at which to draw the icon, 
hlcon is a handle to the icon to draw. It may be a 
cursor handle. rgfHalftone is a word of flags con- 
sisting of the following icon styles which may be 
OR’d together: 



ICS_ NORMAL 

draw the icon as it would normally 
appear 

ICS_ HALFTONE 

draw the icon with a halftone pattern 
where black normally appears 

ICS_ INVERT 

draw the icon inverted - ie black where 
white is and white where black is. 



WinDrawBorder 



Format 



void far WinDrawBorder (hps, 
HPS hps; 

LPRECT lprc; 



INT cx; 
INT cy; 



lprc, cx, cy, rgfCmd) 
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UINT rgfCmd; 

Description 

This function draws a border (a rectangular frame) 
bounded by the rectangle * lprc in the specified PS. 
cx is the width of the left and right sides of the 
rectangle, cy is the height of the top and bottom 
sides of the rectangle. 

The values for rgfCmd are: 



WinDrawBorder() Flags 
DB_ PATCOPY 

The PATCOPY raster op is used 

DB_ PATINVERT 

The PATINVERT raster op is used 

DB_ STANDARD 

cx and cy are multiplied by the system 
SV_ CXBORDER and SV_ CYBORDER 
constants. 

DB_ DLGBORDER 

A standard dialog border is drawn. If 
DB_ PATCOPY specified, then an active 
dialog border is drawn. If 
DB_ PATINVERT is specified, then an 
inactive dialog border is drawn. 

DB_ INTERIOR 

Specifies that the interior of the border is 
drawn with the current pattern back- 
ground color. 

The border is drawn in the current pat- 
tern foreground color 

Example 

For example, here is a call to draw a rectangular 
frame whose width is twice the SV_ CXBORDER 
and SV_ CYBORDER values with the standard 
window frame color: 

WinDrawBorder (hps, (LPRECT) &rc, 

2 , 2 , DB_PATCOPY j DB_STANDARD) ; 



WinlnvertRect 



Format 



void WinlnvertRect (hps, lprc) 
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Description 

This function inverts the area of hps described by 
the rectangle *lprc. 



4.1.4 Window Frames 



4. 1.4.1 Window Frame Architecture 

A standard application window has the following parts: 
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Part 


Description 


#1 


Wide sizing border 


#2 


System menu 


#3 


Title Bar 


#4 


Minimize/Maximize box 


#5 


Application menu 


#6 


Vertical scroll bar 


#7 


Horizontal scroll bar 


#8 


Client window 



The window that contains all of these parts is called the "Frame Win- 
dow". Each of the parts that make up a window, such as the title bar and 
menu, are separate child windows of the frame window. All of these child 
windows ( except the client area) are called "Frame Controls". 
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The client area is not a frame control; it is an instance of a window class 
implemented by the application. 

The frame window and all of the frame controls are implemented with 
standard preregistered window classes. In this section, we will describe 
the behavior of each of these window classes, and how they are used with 
an application window class to implement a standard application window. 

The frame window is the "glue" that holds together all of the frame con- 
trols and the client that make up an application window. It is responsible 
for arranging the frame controls and the client window as the frame win- 
dow is sized and moved. It is also responsible for routing certain messages 
to its frame controls and the client window. 

Each of the frame controls is known to the frame window by its window 
ID. Below is a list of the standard ID values that identify each frame con- 
trol: 



Standard Frame Control IDs 

FID_ SIZEBORDER 

Wide sizing border 

FID-SYSMENU 

System menu 

FID. TITLEBAR 
Title Bar 

FID-MINMAX 

Minimize/Maximize box 

FID- MENU 

Application menu 

FID-VERTSCROLL 

Vertical scroll bar 

FID-HORZSCROLL 

Horizontal scroll bar 

FID- CLIENT 

Client window 

As with all controls, when something interesting happens to a frame con- 
trol (a scroll bar click or the menu key is pressed, for exampl e), the frame 
control notifies its owner with window messages. The owner o f each of 
the frame controls is the frame window itself. Messages that may be of 
interest to the client window are sent to the client by the frame window. 
The frame window has no owner. 
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There are two ways that you can create a standard window and frame con- 
trols. You can create the frame window and all of its frame controls expli- 
citly, or you can use the WinCreateStdWindowQ function, which will 
create a frame window plus all of the standard controls, using the frame 
window style to determine which of the standard frame controls are to be 
created. 



4. 1.4. 2 The Frame Window Class 

The standard window frame class name is WC-FRAME. The frame win- 
dow is a sync paint window. 



Frame Window Styles 

When a window of class WC-FRAME is created, some of the standard 
frame controls may be also automatically created depending on the win- 
dow style of the frame window. The window style also governs the 
appearance of the frame window border as well. 

The frame window styles below are also used with WinCreateStdWindowQ 
and WinCreateFrameControlsQ below. 



Standard Frame Styles 
Flag 

FS_ TITLEBAR 

Title bar 

FS-SYSMENU 

System menu 

FS-MENU 

Application menu 

FS-MINMAX 

Minimize/Maximize box 

FS-VERTSCROLL 

Vertical scroll bar 

FS-HORZSCROLL 

Horizontal scroll bar 

FS-SIZEBORDER 

Wide sizing border 

FS_ BORDER 

Window is drawn with a thin border 



232 




Window Management Functions 



FS_ DLGBORDER 

Window is drawn with a standard dialog border 
FS-ACCELTABLE 

Causes an accelarator table to be loaded for this frame win- 
dow from the resource file identified on the Win- 
CreateStdWindow call. 

FS_ STANDARD 

Same as (FS_ TITLEBAR j FS-SYSMENU ! FS-MINMAX J 
FS-SIZEBORDER | FS-MENU j FS_ ACCEPTABLE) 

All of the styles except FS_ BORDER and FS_ DLGBORDER only have an 
effect when the WC-FRAME window is created. At this time, these styles 
are used to determine whether the corresponding frame control should be 
created. Once a frame control is created, changing these style bits has no 
effect: to add or remove frame controls the WinSetParent() call may be 
used, or the frame controls may be created or destroyed explicitly. 



4-1. 4-2. 2 Frame Window Messages 

The following messages are processed by the frame window. Many of these 
messages are standard window management messages; they are included 
here to illustrate the behavior of the frame window. 



WM_ SYS COMMAND 

Description of this message is given in the section on Con- 
trols. 



WM_ FORMATFRAME 



Format 



WM_F ORMATFR AME 
lParaml: OL; 

lParam2: OL 

Returns: BOOL fProcessed; 

Description 

This message is sent to a frame window to calcu- 
late the sizes and positions of all of the frame con- 
trols and the client window. 

This message is passed on to the FID_ CLIENT 
window by the standard frame window. If the 
FID_ CLIENT window returns fProcessed == 
FALSE, then the frame window performs the 
default action; otherwise it is assumed that the 
FID_ CLIENT window processed the message. 
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The WC_ FRAME default processing of this mes- 
sage is to first call WinFormatFrameQ and then 
calling WinSetMultWindowPosQ to position the 
frame controls. 



WM_ UPDATEFRAME 



Format 



WM_UPDATEFRAME 
lParaml: ULONG style; 

lParam2: OL 

Returns: BOOL fProcessed; 

Description 

This message is sent by an application after frame 
controls have been added or removed from the win- 
dow frame to reformat and update the appearance 
of the window frame as a result of the change. 

lParaml contains FS_ style bits that indicate 
which frame controls were added or removed. 

Since this message will cause any redrawing that is 
necessary, you should ensure that no drawing takes 
place when you actually add or remove a frame 
control, to prevent unnecessary redrawing. If you 
use WinSetParentQ, this is done by setting the 
fRedraw parameter to FALSE. 

This message is passed on to the FID_ CLIENT 
window by the standard frame window. If the 
FID_ CLIENT window returns fProcessed == 
FALSE, then the frame window performs the 
default action; otherwise it is assumed that the 
FID_ CLIENT window processed the message. 

The default WC_ FRAME processing of this mes- 
sage is to simply send a WM_ FORMATFRAME 
message to itself. 

To add a control, simply create the window with a 
zero size, or use WinSetParentQ with fRedraw == 
FALSE. To remove a control, use WinSetParentQ 
with fRedraw == FALSE. Then set the appropri- 
ate style bit, and send the WM_ UPDATEFRAME 
message to the frame window. 



WM_ ERASEBACKGROUND 
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Format 



WM_ERASE BACKGROUND 

lParaml: HPS hpsFrame; 

lParara2 : LPRECT IprcPaint; 

Returns: BOOL fProcessed; 

Description 

This message is sent by WC_ FRAME and 
WG_ DIALOG windows to the FID_ CLIENT win- 
dow in order to allow the client window to erase 
the background of the frame window synchro- 
nously. 

• hpsFrame is the HPS for the frame window. 

• IprcPaint contains a far pointer to a rectangle 
to be painted. 

If the client window processes the message, TRUE 
is returned. If FALSE is returned and a 
FID_ CLIENT window exists, then the area of the 
frame covered by the FID_ CLIENT window is 
erased in the system window background color. If 
FALSE is returned and no FID_ CLIENT window 
exists, then the entire frame window is erased in 
the system window background color. 



J h l. 4-2-3 Default WC— FRAME Processing of Standard Messages 

hlere is a list of the default processing of various messages by 
WC_ FRAME class windows: 



WM_ ACTIVATE 

First sends TBM_ SETSTATE message to FID_ TITLEBAR 
control, if it exists, to hilite or unhilite the titlebar. If 
FS-DLGBORDER then dig border is redrawn in either hil- 
ited or unhilited state, as necessary. Next sends the 
WM_ ACTIVATE message to the FID_ CLIENT window. 
Upon return, if the window is being deactivated and the 
caret is set to the frame window or any of its controls, the 
caret is destroyed. 

WM_ CALCVAL1DRECTS 

Passed to WinDefWindowProcQ 

WM-SIZE: 

Sends a WM-FORMATFRAME message to self. 

WM_ FORMATFRAME 

First, the message is sent to the FID_ CLIENT window If 
FID- CLIENT returns TRUE to indicate that the message 
was processed by the client window, then no additional 
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processing is performed. Otherwise, WinFormatFrameQ is 
called, with IprcFrame rectangle equal to the frame window 
rect adjusted based on the presence of the FS-DLGBORDER 
or FS_ BORDER controls, or the existence of the 
FID_ SIZEBORDER control. When WinFormatFrameQ 
returns, WinSetMultWindowPosQ is called to reposition the 
frame controls. 

WM_ UPDATEFRAME 

First, the message is sent to the FID_ CLIENT window. If 
FID_ CLIENT returns TRUE to indicate that the message 
was processed by the client window, then no additional pro- 
cessing is performed. Otherwise, If lParaml contains 
FS_ SIZEBOX, the area occupied by the size box is invali- 
dated. A WM_ FORMATFRAME is sent to self. 

WM_ QUERYWINDOWPARAMS 

Passed to FID_ TITLEBAR control, if it exists, in order to 
obtain the text of the window title. 

WM_ SETWINDOWPARAMS 

Passed to FID_ TITLEBAR control, if it exists, in order to 
set the text of the window title. 

WM_ L/M/RBUTTONDOWN 

WinSetActiveWindowQ is called, with fSetFocus == TRUE. 

WM_ COMMAND 

Passed to FID_ CLIENT window 

WM-HSCROLL 

Passed to FID_ CLIENT window 

WM_ VSCROLL 

Passed to FID_ CLIENT window 

WM_ PAINT 

If FS_ BORDER then thin frame is drawn. If 

FS_ DLGBORDER then dialog border is drawn in either hil- 

ited or unhilited state, as necessary. 

WM_ ERASEBACKGROUND message is sent to 
FID- CLIENT window. If WM_ ERASEBACKGROUND 
message returned FALSE (client did not process), then client 
area is erased with the standard window background color. 

WM_ SYSCOMMAND 

Below is a list of the standard system commands and how 
they are handled by the frame processing: 

System Command Values 
Command 



SC_ SIZE 
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control. 

SC-MOVE 

Send a CPM_ MOVE message to the control with 
the ID FID_ TITLEBAR, assumed to be the title 
bar control. 

SC_ MINIMIZE 

Minimizes the frame window or restores it to a 
remembered size and position. 

SC_ MAXIMIZE 

Maximizes the frame window or restores it to a 
remembered size and position. 

SC_ NEXT 

Cycle the active window status to the next top- 
level window. 

SC-APPMENU 

Send a MM_ STARTMENU message to the control 
with the ID FID-APPMENU, assumed to be the 
application menu control. 

SC-SYSMENU 

Send a MM_ STARTMENU message to the control 
with the ID FID-SYSMENU, assumed to be the 
system menu control. 



4-1. 4-2-4 Frame Notifications 

The frame window always sends notification messages to the child window 
that has the window ID of FID_ CLIENT. If no window exists with that 
ID, no notification messages are sent. 

All messages that are not explicitly processed by the frame window are 
simply sent on to the FID_ CLIENT window. This includes the 
WM_ COMMAND message and the WM-HSCROLL and WM-VSCROLL 
messages posted by the menu and scroll bar frame controls, respectively. 



WM_ QUERYMINMAXINFO 



Format 



WM_QUERYM I NMAX INFO 

lParaml: POINT lprgptMinMax{3> ; 

lParam2 : 0; 

Returns : OL ; 

Description 

This message is sent by the frame window to the 
client window before it performs a minimize or a 
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maximize operation, upon recieving a 

WM_ SYSCOMMAND message with lParaml equal 

to either SCL MINIMIZE or SC_ MAXIMIZE. 

lParaml is a far pointer to an array of 3 POINT 
structures. These points should be set to the values 
indicated below: 

rgptMinMaxfOJ- = Minimized size 
rgptMinMax-fl}- = Maximized size 
rgptMlnMax-(2)- = Maximized position, relative 
to the parent of the MinMax control 
owner window. 



4. 1.4.3 Standard Window Frame Routines 



WinCreateStd Window 



Format 



HWND FAR PASCAL WinCreateStdWindow (hab, hwndParent, 

style, IpszTitle, IpszClientClass, styleClient, 
idModule, idResource, lphwndClient) 

HWND hwndParent ; 

ULONG style; 

LPSTR IpszClientClass; 

LPSTR IpszTitle; 

ULONG styleClient; 

UINT idModule; 

I NT idResource ; 

HWND far * lphwndClient; 

HAB hab; 

Description 

WinCreateStdWindow() creates and returns a 
WC_ FRAME class window whose parent is 
hwndParent. The frame window handle is 
returned, or NULL if the creation was unsuccess- 
ful. 

style is the window style of the WC_ FRAME win- 
dow, which is a combination of any of the standard 
WS_ window styles and the FS_ frame styles. 

IpszClientClass is a pointer to the class name of a 
window class name; if non-NULL, a client window 
is created of the specified class and with the win- 
dow style styleClient, and returned in 
^lphwndClient. Generally, WS_ VISIBLE should 
be included in styleClient. 

If FS_ TITLEBAR is specified, a WC_ TITLEBAR 
control is created with the text pointed to by 
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lpszTitle. If FS-TITLEBAR is not specified, this 
parameter is ignored. 

If FS_ MENU is specified, idModule and idResource 
are the module handle, returned by the DOS 
DosLoadModule call, and ID of the menu template 
and accelerator table resources to load. If 
FS-MENU is not specified, idModule and 
idResource are ignored. Note that it is the 
application’s responsibility to ensure that the ID of 
the menu resource and accelerator table resource 
are the same. 

All of the frame controls and the client window are 
created with the standard FID_ window IDs. 

If WS_ VISIBLE is specified in style, the standard 
window’s size and position are obtained from the 
Shell before the window is shown. (The Win- 
QueryTaskSizePos function is used). 

If WS_ VISIBLE is NOT specified in style, the 
frame window is created invisible with a zero size 
and positioned at bottom left. You MUST later 
size, position, and show the window with a call to 
WinSetWindowPosQ. This is the recommended 
way to created a standard window which is NOT a 
main window. 

WinCreateStdWindowIndirect 



Format 



HWND hwndFrame — WinCreateStdWindowIndirect (hab, 

hwndParent, style, IpszClientClass , lpszTitle, 
styleClient, lpMenuTemplate, IpAccelTable, 
lpHwndCl ient) 

HWND hwndParent; 

ULONG style; 

LPSTR IpszClientClass; 

LPSTR lpszTitle; 

ULONG styleClient; 

UCHAR FAR * lpMenuTemplate; 

UCHAR FAR * IpAccelTable 
HWND far *lphwndClient; 

HAB hab; 

Description 

This function is identical to WinCreateStdWin- 
dow, except that the lpMenuTemplate parameter 
is a pointer to a menu template and the IpAccelT- 
able parameter is a pointer to an in-memory 
accelerator table definition. These parameters 
replace the idModule, returned by the DOS 
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DosLoadModule call, and idResource parameters of 
WinCreateStdWindowQ. A NULL value implies 
that no menu or accelerator table is present, 
respectively. 

WinCalcFrameRect 



Format 



void WinCalcFrameRect (hwndFrame, lprc, fClient) 
HWND hwndFrame; 

LPRECT lprc; 

BOOL f Client- 

Description 

This function is used to calculate a client rectangle 
from a frame rectangle, or a frame rectangle from 
a client rectangle, depending on the fClient flag. 

The rectangle at *lprc is modified. 

If fClient is FALSE, *lprc points to a client rectan- 
gle. *lprc is modified such that corresponds a size 
and position of hwndFrame that would result in a 
client window rectangle the same as that originally 
pointed to by lprc. 

If fClient is TRUE, *lprc points to a frame rectan- 
gle. *lprc is modified such that it corresponds to 
the client window rectangle if the size and position 
of the hwndFrame were changed to the rectangle 
originally pointed to by lprc. 

This function works even if hwnd is hidden. In 
fact, it is important that hwnd should be hidden if 
it is required that the window show a particular 
client rectangle when the window is first shown. 

WinCreateFrameControls 



Format 



BOOL FAR PASCAL WinCreateFrameControls (hwndFrame, 
style, IpszTitle, idModule, idResource) 
register HWND hwndFrame; 

ULONG style; 

LPSZ IpszTitle; 

UINT idModule; 

I NT idResource; 

Description 

This function creates all of the standard frame 
controls for a window, based on the style parame- 
ter. All of the controls are created with 
hwndFrame as their owner and parent. If 
FS_ TITLEBAR is specified in style, a 
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WC_ TITLEBAR window is created with the text 
pointed to by IpszTitle. If FS-MENU is specified, 
a menu is loaded from the resource template 
specified by idModule, returned by the DOS 
DosLoadModule call, and idMenu. 

All of the controls are created with the standard 
FID_ window IDs. 

This function is typically used when the standard 
frame controls are to be used with a non-standard 
(i.e., non-WCL FRAME) frame window class. 

WinF ormatF rame 



Format 



INT FAR PASCAL WinFormatFrame (hwndFrame, 

IprcFrame, lprgswp, cswpMax, IprcClient) 
HWND hwndFrarae; 

LPRECT IprcFrame; 

LPSWP lprgswp; 

INT cswpMax; 

LPRECT IprcClient; 

Description 

This function calculates the size and position of all 
of the standard frame controls within a frame win- 
dow. For all of the standard frame control chil- 
dren of hwndFrame that exist, (identified by their 
FID- window ID values), this function fills in an 
array of SWP structures with the window size and 
positions. This array of SWP structures is then 
typically passed to WinSetMultWindowPos() to 
actually move and size the frame controls to the 
desired locations. 

hwndFrame is the frame window handle whose 
children are to be positioned. 

IprcFrame is a far pointer to a rectangle within 
which to format the children. This is typically the 
window rectangle of hwndFrame, but in cases 
where the frame window has a wide border 
(FS_ DLGBORDER for example), this rectangle is 
inset by the size of the border. 

lprgswp is a far pointer to an array of SWP struc- 
tures, and cswpMax is the maximum number of 
SWP structures that will fit in this array. This 
array should have at least 12 elements. 

This function returns the actual number of SWP 
structures returned in the array. The array is 
filled in in the order of FID_ values shown in the 
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table; the SWP structure for the FID_ CLIENT 
window is always the last element of the array. 

The client rectangle is returned in *lprcClient. 

This rectangle is in frame window coordinates, and 
represents the area occupied by the FID_ CLIENT 
window. If IprcClient is NULL, no rectangle is 
returned. 

This function is typically used only by applications 
that wish to have a non-standard window frame 
layout. 



4. 1.4. 4 Using Frame Windows 

To add or remove a menu, scroll bar, or other frame control, see the 
WM_ UPDATEFRAME message. 

You can use WinLoadMenuQ to load more than one menu, and use Win- 
SetParentQ and WM_ UPDATEFRAME to switch between the loaded 
menus. 

When sizing, moving, or activating an application window, the frame win- 
dow handle should be used. The client window handle should be used for 
things that directly affect the client window: drawing, sending messages, 
etc. 



4. 1.4. 5 Alternate Window Frame Formatting 

By processing the WM_FORMATFRAME and WM_ UPDATEFRAME 
messages, it is possible for applications to change the default window 
frame formatting. 

WM_ FORMATFRAME processing is usually done by first calling WinFor- 
matFrameQ, and changing or adding additional SWP structures to the 
SWP array based on the results of WinFormatFrame(). Then, WinSet- 
MultWindowPos() is called with the changed SWP array. 

4.1.5 The Title Bar Control 

The title bar control is the frame control that is used to display the appli- 
cation window title. It is also used to display the window active/inactive 
status of the frame window, and to implement window flashing. 

The title bar control also implements the user interface for moving the 
frame window. 
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The class name to use when creating title bar controls is WC_ TITLEBAR. 
The standard ID for a title bar control in a frame window is 
FID_ TITLEBAR. 



4. 1.5.1 Title Bar Style 

There is only one title bar style; thus there are no available style bits. 



4. 1.5. 2 Title Bar Messages 

The window text of the title bar control is displayed in the title bar; the 
window text may be accessed via the WM_ SETWINDOWP ARAMS and 
WM_ QUERYWINDOWP ARAMS messages. 

The following messages are processed by the title bar control, in addition 
to the standard window management messages: 

Title bar state flag constants: 



State Flag. 

Meaning 

TBF_ FLASH 

Titlebar state is flashing. 

TBF_ FLASHHILITE 

Titlebar is flashing and hilit. 

TBF_ HILITE 

Titlebar state is hilit. 



TBM_ QUERYSTATE 



Format 



TBM_QUERYSTATE 
lParaml : OL 

lParam2 : OL 

Returns: UINT rgfTitleState; 

Description 

Returns a combination of the TBF_ constants 
above: 

• TBF_ FLASH if the titlebar is currently flash- 
ing 
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• TBF_ FLASHHILITE if titlebar is flashing and 
in hilited state 

• TBF-HILITE if titlebar is in hilited (active) 
state. 



TBM_ SETSTATE 



Format 



TBM_SETSTATE 

lParaml : UINT rgfNewState; 

lParam2: UINT rgfStateMask; 

Returns: UINT rgfOldState; 

Description 

Changes the state of the title bar. lParaml con- 
tains flags selecting the new state, and lParam2 
contains flags indicating which state will be 
selected. For example, rgfNewState = 

TBF_ FLASH, rgfStateMask == TBF_ FLASH 
starts the window flashing. rgfNewState = 0, 
rgfStateMask == TBF_ FLASH ] TBF-HILITE 
unhilites the title bar and stops it flashing. 

Returns the previous state (ANDed with rgfSta- 
teMask) of the title bar. 



TBM_ TRACKMOVE 



Format 



TBM_TRACKMOVE 

lParaml: BOOL fMouse; 

lParam2 : POINT ptMouse; 

Returns: OL; 

Description 

Initiates the window movement user interface 
code. The owner window of the title bar is moved. 

If fMouse is TRUE, the movement was initiated 
with the mouse, and lParam2 contains the initial 
mouse position. Otherwise, lParam2 contains OL. 

The processing of this message causes a 
WM_ QUERYMOVESIZEINFO message to be sent 
to the control owner. The processing of this mes- 
sage also results in a call to SetWindowPos. 
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4. 1.5. 3 Title Bar Notification Messages 



WM_ QUERYMOVESIZEINFO 



Format 



WM_QUERYMO VE S I ZE I NF 0 

lParaml: LPRECT * IprcTrackBoundry ; 

lParam2: POINT FAR IprgptSize [2] ; 

Returns: BOOL f Continue; 

Description 

This message is sent by the title bar control before 
moving, or by the size control before sizing. It is 
used to obtain limiting widths and rectangles that 
limit the sizing or moving operations. 

For the title bar, this message is sent once to the 
title bar owner at the start of the processing of the 
TM_TRACKMOVE message. 

For the size control, this message is sent once to 
the size control owner at the start of the process- 
ing of the SZM_TRACKSIZE message. 

lParaml is a far pointer to a rectangle, which is 
initialized to the tracking limit rectangle. When 
the window is being moved, no edge of the window 
may fall outside this rectangle. 

lParam2 is a long pointer to an array of two 
POINT structures. IprgptSize [0] is set to the 
minimum tracking size, and lprgptSize[l] is set to 
the maximum window tracking size. 

Returns TRUE to continue tracking, FALSE to 
abort tracking. 

4.1.6 The Size Control 

The size control is used to implement the wide window sizing borders. 

This controls implement the window sizing user interface. After a size 
change is requested, size controls notify their owners with an 
SZM_ SETPOS message. 

The class name to use when creating size controls is WCLSIZE. The stan- 
dard IDs for the size borders when used with the standard WC-FRAME 
window class are FID_ WIDESIZE. 
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4. 1.6.1 Size Control Styles 

There is only one Size Control style so there are no available style bits. 



4. 1.6. 2 Size Control Messages 



SZM_ TRACKSIZE 



Format 



S ZM_TRACKS I ZE 

lParaml: BOOL fMouse; 

lParam2 : POINT ptMouse; 

Returns: OL; 

Description 

Initiate the window sizing user interface code. The 
owner window of the size control is moved. 

If fMouse is TRUE, the size operation was initiated 
with the mouse, and lParam2 contains the initial 
mouse position. Otherwise, lParam2 contains OL. 

The processing of this message causes a 
WM_ GETSIZEINFO message to be sent to the 
control owner. 



4. 1.6. 3 Size Notification Codes 

The only notification code is the WM-QUERYMOVESIZEINFO message 
which is described in the Title Bar Notification messages section. 

4.1.7 The Minimize/Maximize Control 

The Minimize/Maximize controls (MinMax controls) are used as input 
translation controls, which simply translate mouse down messages into 
WM_ SYSCOMMAND messages that get sent to the owner window. When 
drawn, they typically appear as small icon buttons at the right edge of the 
title bar of the frame window. 

The class name to use when creating min/ max button controls is 
WC_ TITLEBAR. The standard ID for the minimze and maximize button 
control in a frame window is FID-MINMAX. 
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4. 1.7.1 MinMax Control Styles 



MinMax Control Styles 
Style 

MMS_ MAXBUTTON 

With this style the control provides the user interface for 
maximizing. Can be used with MMS_ MINBUTTON. 

MMS_ MINBUTTON 

With this style the control provides the user interface for 
maximizing. Can be used with MMS_ MINBUTTON. 

If both the MMS_ MAXBUTTON and MMS_ MINBUTTON styles are 
used, the control appears and operates as both a min and a max button, 
with the min button to the left of the max button. 

When clicked on, the min/max control simply sends a 
WM-SYSCOMMAND message to the owner window. If the owner window 
is the frame window, it’ll send a \VM_GETMINMAXINFO message to the 
client window, and based on the result, perform the minimizing or maxim- 
izing operation. 

If a minimize button is clicked on, a WM_SYSCOMMAND will be sent to 
the owner window, with lParaml equal to SC_ MINIMIZE. 

If a maximize button is clicked on, a WM_ SYSCOMMAND will be sent to 
the owner window, with lParaml equal to SC_ MAXIMIZE. 

4.1.8 Dialog Boxes 

A dialog box is a window that contains one or more child windows, typi- 
cally used to provide a means for an application to gather input from the 
user. It is often a temporary window that is created for special purpose 
input and destroyed immediately after use. 

There are two types of dialog boxes: modeless dialogs and modal dialogs. 
A modeless dialog allows other application windows to be activated after 
it has been created. A modal dialog keeps control until the Win- 
DismissDlg function is called. The user is not able to activate other win- 
dows belonging to the same application until he has finished interacting 
with the modal dialog. 

Dialog boxes are created from a "Dialog Template". The dialog template 
defines the position, appearance, and window ID of the dialog window, and 
each of its child windows. Dialog Templates can be used to create dialog 
windows of any window class, containing controls of any window class. 

For standard dialog boxes, the dialog window itself is created with the 
WC_ DIALOG class, and its children are any of the preregistered control 
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classes. Applications can create dialogs with application registered con- 
trols as well. 

Standard WC_ DIALOG dialog boxes also have a "Dialog Procedure". 

The dialog procedure is identical to any normal window procedure. 
Presentation Manager always calls the dialog procedure, giving it a chance 
to process the message. If the dialog procedure does not need to handle 
the message, it generally passes it on to WinDefDlgProcQ. Win- 
CreateDlgQ automatically performs the "sub-classing" that is required. 
Note that when a dialog box is created with WinCreateDlgQ, the dialog 
proc won’t receive a WM_ CREATE message. This is because the dialog 
window does not get sub-classed until AFTER it is created. 

Presentation Manager supports a standard user interface for dialog boxes. 
Generally, when a dialog proc doesn’t handle a keydown or mouse button 
message, it must return FALSE. Presentation Manager then performs 
additional processing on this message to implement the user interface. 

The dialog window itself is called the "Dialog Window", and the child con- 
trol windows are called "Dialog Items". Each dialog item is identified by a 
unique ID that is passed to WinCreateWindowQ as the item is created. 

The window handle of a particular item may be obtained with WinWin- 
dowFromlDQ. 

As each dialog item window is created, its text is processed with WinSub- 
stituteStringsf), which may cause WM_ SUBSTITUTESTRING messages 
to be sent to the dialog procedure. See "WinSubstituteStrings" for more 
information. 



4. 1.8.1 The Dialog Procedure 

A dialog procedure is a normal window procedure that is automatically 
sub-classed to each instance of the WC_ DIALOG window class. The dia- 
log procedure must be declared as follows: 



DialogProc 



Format 



ULONG EAR PASCAL DialogProc (hwnd, msg, 
lParaml, lParam2) 

HWND hwnd ; 

UINT msg; 

ULONG lParaml; 

ULONG lParam2 ; 
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This procedure is no different from other window procedures except that it 
can receive predefined window messages intended especially for dialog 
boxes. It won’t receive a WM_ CREATE message, but it can get the same 
information from the WM_ INITDIALOG message. 

The first four parameters are the same as with any window procedure, 
hwnd is always the window handle of the dialog box window. 

Typically, the dialog procedure will process some, but not all of the mes- 
sages passed to it. If it does not wish to process a message, it should pass 
it on to WinDefDlgProc(). 



4. 1.8. 2 Dialog Templates 

Dialog Templates are data structures used to define dialog boxes. These 
templates can be loaded as resources or created dynamically in memory. 
Dialog Templates can be used to create windows of any window class that 
contains child windows of any window class. For standard dialog boxes, 
the dialog window itself is created with the WC_ DIALOG class, and its 
children are any of the predefined control classes. 

The dialog template specifies all the information required to create a dia- 
log window and its children: the class, text, position, size, and the window 
ID. 



4-1. 8. 2.1 Dialog Coordinates 

Coordinates in a dialog template are specified in "dialog coordinates". 
Dialog coordinates are based on the size of the system font: a unit in the 
horizontal direction is 1/4 the system font average character width, and a 
unit in the vertical direction is 1/8 the system font character height. The 
origin is the bottom left corner of the dialog box. 



4-1. 8. 2. 2 Dialog Template Format 
Dialog Template format: 



typedef struct 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 
UINT 

DLGTITEM 

UCHAR 

DLGTEMPLATE ; 



cbTemplate; 
type; 
codepage ; 
of frgti; 
statusTemp late; 
co f fPresParams ; 
rgof fPresParams [ 
rgti [ ?] ; 

rgbData [ ?] ; 



cof fPresParams] ; 
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cbTemplate 

is the overall length of the dialog template in bytes. 

Type identifies the dialog template format type. This value is 
currently always zero. 

codepage 

The codepage of the text in the template. This is currently 
always 850. 

offrgti Offset to array of DLGITEM structures from beginning of 
template. 

statusTemplate 

contains status information for the entire dialog box. This 
currently always has a value of zero. 

coffPresParams 

Currently always zero 

rgoffPresP arams 

Currently always an array of zero dimension 

rgti Array of DLGITEM stuctures, described below. The first ele- 
ment of this array describes the primary window. All other 
items in the array are children of this window. The number 
of children is specified in the cChildren field of the first 
DLGITEM. 

rgbData 

Array of bytes. Window class names, text strings, control 
data and presentation parameters are stored here. 

Dialog Item format: 



typedef struct DLGTITEM 



UINT 


status Item; 


UINT 


cChildren; 


UINT 


cchClassName; 


UINT 


of fClassName; 


UINT 


cchText ; 


UINT 


of fText; 


ULONG 


Style; 


I NT 


x ; 


I NT 


y; 


I NT 


cx; 


I NT 


cy ; 


UINT 


id; 


UINT 


iof fPresParams 


UINT 


of fCtlData; 


DLGTITEM; 
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statusltem 

contains status information for the item. This must have 
the value 0. 



cChildren 

is a count of the child windows that are owned by this win- 
dow. If cChildren is non-zero, then the next cChildren win- 
dows will be created as children to this window. Each win- 
dow can have any number of child windows, which allows for 
a fully tree-structured arrangement. 

cchClassName 

is the length of window class name. If a length of zero is 
specified then ClassOffset is assumed to contain a system 
class identifier. This is the length of the significant charac- 
ters in the class name excluding the terminating NULL. 

offClassName 

is the offset within the dialog template of the string specify- 
ing the window class name. If a cchClassName of zero is 
specified then this offset is assumed to be a system class 
identifier. The class name should be a NULL terminated 
ASCII string. 

is the length in bytes of the text data associated with the 
control. This is the length of the significant characters in 
the text excluding the terminating NULL. 

is the offset within the dialog template of the text data with 
which the window should be initialized. The text should be 
a NULL terminated ASCII string. 

is the style of the window. The first 8 bits are the standard 
WS_ style bits, and the remaining 24 bits are available for 
class-specific use. 

are the x and y coordinates of the window. For the control 
windows, within the dialog these are specified in dialog coor- 
dinates, with x and y relative to the origin of the dialog win- 
dow. 

Cx and Cy 

are the x and y extent of the window. 

id is the ID number for this window. 

ioffPresParams 

Currently always zero. 

offCtlData 

is the offset within the dialog template of the Control data 
for this window. 



cchText 
offText 
Style 
Xand Y 
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The Dialog Data contains the data for the Text, Class Names, 
CreateParams and PresentationParams for the Dialog Items. This is held 
in an unstructured array of bytes, as large as necessary to contain the 
data. 

Note that this is a fully recursive structure. More than one level of child 
windows may be specified. 



4. 1.8. 3 Dialog Control Groups 

Within a Dialog Box, sets of controls can be aggregated into Groups, 
mainly for the purposes of easier interaction for the end-user. 

Groups are really useful for Button controls, but could apply to other 
types of controls. 

When a set of controls are formed into a group, the user can go from one 
to the next by pressing the arrow keys on the keyboard. The focus 
progresses round all the members of the group, but not members of any 
other group. Note that this implies that controls which themselves pro- 
cess the arrow keys, such as Edit Controls, cannot be formed into a group. 

A group is established by setting the WS_ GROUP style bit for the first 
control in the group. Tfie other members of the group should follow the 
first in the enumeration order (ie follow in the template). The group is 
terminated by the next control which has the WS_ GROUP style - this 
starts the next group. Logically, all the items in a Dialog Box are in one 
group or another. 

The user can go from one group to the next by using the TAB keys. When 
the TAB key is pressed, the focus is moved to the next control in the 
enumeration order which has the WS-TABSTOP style bit set. Normally 
this would be the first member of a group. 

Tab keys are the normal way to get from one Edit Control to the next and 
these controls should always have the WS_TABSTOP style. In fact, this 
is the default for Dialog Templates generated from text' resource files by 
the resource compiler. 



4. 1.8.4 Dialog Box Messages 

A dialog procedure, being a standard window procedure, receives any mes- 
sages that are sent to the dialog box. This includes the standard window 
management messages such as WM_ DESTROY, as well as control 
notifications such as WM_ CONTROL and WM_ COMMAND. 



252 




Window Management Functions 



The dialog procedure may also receive WM_ SUBSTITUTESTRING mes- 
sages, if substitution strings are used in the dialog template. If sent, these 
messages are sent before an item is created. See "WinSubstituteStringsQ". 

Presentation Manager sends the following message after a dialog box is 
created, but before it is made visible: 



WM_ INITDIALOG 



Format 



Message : 
lParaml : 
lParam2 : 
Returns : 



UINT WM_INITDIALOG 
HWND hwndSetF ocus 

LPSTR lpCreateParams 
BOOL fFocusSet 



Description 

This message is sent by WinLoadDlg or Win- 
CreateDlg to a dialog procedure right after a dia- 
log window is created, but before it is shown. This 
message is intended to allow the application to do 
run time initialization of the dialog box. Often it 
will be necessary to initialize text in static and edit 
controls and listboxes at this time, or to check but- 
tons according the the current state of the applica- 
tion. hwndSetFocus is the window handle of the 
control that is going to receive the focus. The 
application may change this by calling WinSet- 
Focus() with the window handle of another control 
in the dialog box and returning TRUE. It should 
otherwise return FALSE. 



lpCreateParams is the lpCreateParams parameter 
passed to WinLoadDlg or WinCreateDlg. 

Notes If any string substitutions were made by WinSub- 
stituteStringf) when the dialog was created, 

WM_ SUBSTITUTESTRING message may have 
been sent BEFORE the WM_ INITDIALOG mes- 
sage is sent. 



When a dialog is created with WinCreateDlg() or WinLoadDlg(), a 
WM_ ADJUSTWINDOWRECT message is sent to each child window after 
the window is created. See the section dealing with the 
WM_ ADJUSTWINDOWRECT message for more detail. 
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4. 1.8. 5 Dialog Styles 

The following styles are defined especially for dialog boxes: 



Dialog Window Styles 
Style 

DS_ DLGFRAME 

The dialog box is created with a special frame that identifies 
it as a dialog box. Most dialog windows are created with 
this style. 

DS_ SCREENALIGN 

The coordinates specifying the location of the dialog box are 
relative to the top left corner of the screen, rather than being 
relative to the owner window’s origin. 

DS-MOUSEALIGN 

The coordinates specifying the location of the dialog box are 
relative to the position of the mouse cursor at the time that 
the window was created. Presentation Manager will attempt 
to keep the dialog box on the screen, if possible. 



4. 1.8. 6 Dialog Box Routines 



WinLoadDlg 



Format 



HWND WinLoadDlg (hab, hwndOwner, lpfnDlgProc, 

idModule, idDlg, lpCreateParams ) 
HWND hwndOwner ; 

FARPROC lpfnDlgProc; 

UINT idModule; 

UINT idDlg; 

LPSTR lpCreateParams; 

HAB hab; 

Description 

This function creates a dialog window from a tem- 
plate in a resource. hwndOwner is the owner win- 
dow. lpfnDlgProc is the dialog procedure, or 
NULL if it doesn’t exist. idModule, returned by 
the DOS DosLoadModule call, is a resource handle 
or NULL for the application resource file. idDlg is 
the id of the dialog within the resource file. 
lpCreateParms points to data that is passed to the 
dialog procedure along with a WM_ INITDIALOG 
message. This function returns the window handle 
of the new dialog box. 
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Notes WinLoadDlg returns immediately after creating 
the dialog box. A WM_ INITDIALOG message is 
sent to the dialog procedure before this function 
returns. 

Also, since each of the controls will be created 
when this function is called, the dialog procedure 
may receive various control notifications. 

A dialog window may be destroyed with WinDes- 
troyWindow(). 

As windows are created from the template, strings 
in the template are processed with WinSubstitute- 
String(). Any resultant 

WM_ SUBSTITUTESTRING messages are sent to 
the dialog procedure before WinLoadDlgQ returns. 



WinCreateDlg 



Format 



HWND WinCreateDlg (hab, hwndOwner, lpfnDlgProc, 
lpDlgTemplate, lpCreateParms) 

HWND hwndOwner ; 

FARPROC lpfnDlgProc; 

DLGTEMPLATE FAR * lpDlgTemplate; 

LPSTR lpCreateParms; 

HAB hab; 

Description 

This function is identical to WinLoadDlgQ (above) 
except that it creates a dialog window from a tem- 
plate in memory rather than a resource file. 
lpDlgTemplate points to a data structure defined 
by DLGTEMPLATE. This function returns the 
window handle of the new dialog box. 



WinProcessDIg 



Format 



UINT WinProcessDIg (hwndDlg) 

HWND hwndDlg; 

Description 

This function processes messages intended for a 
modal dialog. It does not return until the Win- 
DismissDlg call is issued by the dialog procedure 

If the application’s message queue is not empty, 
this function dispatches the messages from the 
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queue to the appropriate window procedure or to 
the dialog procedure, until either a message causes 
the dialog procedure to issue the WinDismissDlg 
call, or until all the messages from the application 
queue are processed. 

If, or when, the application’s message queue is 
empty, this function guarantees the visibility of 
the modal dialog identified by the hwndDlg param- 
eter, i.e. shows the dialog window if it is hidden. 

The function returns with the wResult parameter 
that was provided to the WinDismissDlg function, 
which has hidden the dialog window but has not 
destroyed it. 

Character messages are processed by WinPro- 
cessDlgMsg to implement the standard user inter- 
face user interface. Messages are processed in this 
way ONLY if WinDispatchMsgQ returns FALSE 
(i.e. the window with the focus aid not process the 
message). 



WinDlgBox 



Format 



UINT WinDlgBox (hab, hwndOwner, lpfnDlgProc, 

idModule, idDlg, lpCreateParams) 
HWND hwndOwner ; 

FARPROC lpfnDlgProc; 

UINT idModule; 

UINT idDlg; 

LPSTR lpCreateParams; 

HAB hab; 

Description 

This function creates a modal dialog box. The 
parameters to this function are the same as the 
parameters to WinLoadDlgQ. This function does 
not return until the dialog procedure calls Win- 
DismissDlgQ to destroy the dialog box and relinqu- 
ish control. The value returned by this function is 
equal to the value of the wResult parameter passed 
to the WinDismissDlg() function. 

This function is equivalent to: 
hwndDlg = WinLoadDlg(. . .) ; 
result = WinProcessDlg (hwndDlg) ; 
WinDestroyWindow (hwndDlg) ; 
return (result) ; 
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Notes Values returned by the application’s dialog pro- 
cedure are processed by Presentation Manager. 
They are not returned to the caller of 
WinDlgBoxQ. 



WinDismissDlg 



Format 



VOID FAR WinDismissDlg (hwndDlg, wResult) 
HWND hwndDlg; 

UINT wResult; 

Description 

This function hides the dialog box window and sets 
a flag that causes the 

WinProcessDlg()/WinDlgBox() message processing 
loop to terminate. WinDismissDlg() is required to 
complete processing whenever the 
WinProcessDlgQ/ WinDlgBoxQ function is used to 
create a modal dialog box. This function is called 
from within a dialog procedure. wResult is the 
value which will be returned to the caller of 
WinProcessDlgQ/ WinDlgBoxQ. 

Notes If necessary, WinDismissDlgQ can be called during 
the processing of the WM-INITDIALOG message. 



WinSendDlgltemMsg 



Format 



ULONG WinSendDlgltemMsg (hwndDlg, idltem, msg, 
lParaml, lParam2) 

HWND hwndDlg; 

UINT idltem; 

UINT msg; 

ULONG lParaml; 

ULONG lParam2 ; 

Description 

This function is used to send a message to the 
specified dialog item identified by idltem in the 
dialog box specified by hwndDlg. msg, lParaml 
and lParam2 are the SemdMessage parameters. 
WinSendDlgltemMsg does not return until the 
message has been processed. This function returns 
the value returned by the dialog item’s window 
function. 
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Notes This function is equivalent to: 

WinSendMsg (WinWindowFromID (hwndDlg, idltem), msg, IParai 



WinSetDl gltemlnt 

Format 



BOOL WinSetDlgltemlnt (hwndDlg, idltem, wValue, fSigned) 
HWND hwndDlg; 

UINT idltem; 

UINT wValue; 

BOOL fSigned; 

Description 

This function sets the text of the item with idltem 
in the specified to the string representation of the 
integer wValue. If fSigned is TRUE, wValue is a 
signed integer; otherwise, it is an unsigned 
integer. 

Notes The string is always produced as an ASCII string. 



WinQueryDlgltemlnt 

Format 



INT WinQueryDlgltemlnt (hwndDlg, idDlgltem, 
lpfSuccess, fSigned) 

HWND hwndDlg; 

UINT idDlgltem; 

LPSTR lpfSuccess; 

BOOL fSigned; 

Description 

This function translates the text of a dialog item 
into an integer value. hwndDlg is the dialog win- 
dow handle, idDlgltem is the id of the item to 
translate. If fSigned is TRUE, WinGetDlgltemlnt 
checks for a minus signe before translating the 
number. If lpfSuccess is non-zero, it points to a 
boolean variable. WinQueryDlgltemlnt sets this 
boolean variable to TRUE if it succeeds in 
translating the text without any errors. Other- 
wise, it sets this variable to FALSE. This function 
returns the translated integer value. 

Notes The dialog item string is assumed to be an ASCII 
string. 
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Wi n M a p DlgFoints 



Format 



VOID WinMapDlgPoints (hwndDlg, lprgpt, cpt, 
fCalcWindowCoords) 

HWND hwndDlg; 

POINT FAR * lprgpt; 

I NT cpt; 

BOOL fCalcWindowCoords; 

Description 

This function maps points from dialog coordinates 
to window coordinates, or from window coordi- 
nates to dialog coordinates, depending on the state 
of fCalcWindowCoords. 

lprgpt is a far pointer to an array of POINT struc- 
tures, and cpt is the number of points in this 
array. hwndDlg is the dialog box handle that the 
coordinates will be mapped to or from. 

If fCalcWindowCoords is TRUE, the points in the 
array are assumed to be in dialog coordinates. 
They are mapped to window coordinates relative 
to hwndDlg. 

If fCalcWindowCoords is FALSE, the points in the 
array are assumed to be in window coordinates 
relative to hwndDlg. They are mapped to dialog 
coordinates. 



WinProcessDIgMsg 



Format 



BOOL WinProcessDIgMsg (hwndDlg, lpqmsg) 

HWND hwndDlg; 

LPQMSG lpqmsg; 

Description 

This function determines whether the message 
specified by lpqmsg is intended for the modeless 
dialog box specified by hwndDlg. If so, the mes- 
sage is sent to the dialog window and this function 
returns TRUE. Otherwise, this function returns 
FALSE. This function is typically called from 
within an application’s main loop to allow a mode- 
less dialog box to process the appropriate mes- 
sages, while passing other messages on to its win- 
dow proc. 
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Notes if WinProcessDlgMsg returns TRUE, the message 
has already been processed and should NOT be 
passed on to WinDispatchMsgQ. 

while (WinGetMsg ( (LPQMSG) &qmsg, (HWND) NULL, 0, 0)) { 

if (! WinProcessDlgMsg (hwndModelessDlg, (LPQMSG) &qmsg) ) { 
WinDispatchMsg (LPMSG) &msg) ; 

> 

> 

exit (qmsg . IParamI) ; 



WinEnumDlgltem 



Format 



HWND WinEnumDlgltem (hwndDlg, hwnd, code, fLock) 
HWND hwndD 1 g ; 

HWND hwnd ; 

UINT code; 

BOOL fLock; 

Description 

This function is used to obtain the next or previ- 
ous window handle of a dialog item with either the 
WS-TABSTOP style bit set, or in the same 
"group" as the starting hwnd. 

This function always returns a window handle that 
is an immediate child of hwndDlg, even if hwnd is 
not an immediate child. 

If fLock is TRUE, return the window handle 
locked. 

Wraps around to beginning when obtaining next at 
end of list. Wraps around to end when obtaining 
prev at beginning of list. 

Available code values are shown below. Note that 
only one of these values may be used. 



WinEnumDlgItem() Codes 
Returns: 

EDI-PREVTABITEM 

Previous item with style 
WS_TABSTOP; wraps around to end 

EDI_ NEXTTABITEM 

Next item with style WS_TABSTOP; 
wraps around to beginning 

EDI-FIRSTTABITEM 

First item in dialog with style 
WS_TABSTOP; hwnd is ignored 
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EDI-LASTTABITEM 

Last item in dialog with style 
WS-TABSTOP; hwnd is ignored 

EDI- PREVGROUPITEM 

Previous item in the same group; wraps 
around to end 

EDI- NEXTGROUPITEM 

Next item in the same group; wraps 
around to beginning 

EDI- FIRSTGROUPITEM 

First item in the current group 

EDI- LASTGROUPITEM 

Last item in the current group 



4.1.9 Message Boxes 

A message box is a special predefined dialog window that any application 
can use to display messages and get simple input from the user. A mes- 
sage box contains a specified caption and message and up to four pushbut- 
tons. The message box is displayed in the center of the screen. Message 
boxes can also contain any one of a predefined set of icons. 

The message box may be "Application Modal" or "System Modal". Appli- 
cation modal boxes do not allow the user to activate any other window in 
belonging to the same application before responding to the message box, 
whild System Modal message boxes disable the entire system. System 
modal message boxes are used to notify the user of serious, potentially 
damaging, errors that require immediate attention (for example, running 
out of memory). 



4. 1.9.1 Message Box Functions 



WinMessageBox 



Format 



UINT FAR WinMessageBox (hab. hwndOwner, idHelp, 
IpszText, IpszCaption, rgfStyle) 

HAB hab; 

HWND hwndOwner; 

UINT idHelp; 

LPSTR IpszText; 

LPSTR IpszCaption; 

UINT rgfStyle; 
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Description 

This function creates and displays a message box. 
hwndOwner specifies the owner of the message box 
and IpszText and IpszCaption specify the text con- 
tent and the caption content of the message box 
respectively. If IpszCaption is NULL, the default 
caption "Error" is displayed. The Owner window is 
activated when the WinMessageBox returns. 

rgfStyle is a bit array specifying the contents and 
function of the message box. Any of the following 
combinations can be used: 

If multiple lines are required in the text of the mes- 
sage, carriage return characters may be inserted in 
*lpszText. 

The window ID of the message box is set to idHelp. 
This value is passed to the HK—HELP hook if the 
WM_ HELP message is received by the message 
box. See the description of the HK—HELP hook 
for more detail. 



WinMessageBox() Styles 
Meaning 

MB- OK 

Message box contains an Ok push but- 
ton. 

MB-OKCANCEL 

Message box contains Ok and Cancel 
push buttons. 

MB-RETRYCANCEL 

Message box contains Retry and Cancel 
push buttons. 

MB_ ABORTRETRYIGNORE 

Message box contains three push but- 
tons: Abort, Retry, and Ignore. 

MB-YESNO 

Message box contains two push buttons: 
Yes and No . 

MB-YESNOCANCEL 

Message box contains three push but- 
tons: Yes, No, and Cancel. 

MB_ HELP 

Message box contains a help pushbutton. 
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MB-ICONHAND 

A hand icon appears in the message box. 

MB_ ICONQUESTION 

A question mark icon appears in the 
message box. 

MB_ ICONEXCLAMATION 

An exclamation point icon appears in the 
message box. 

MB_ ICONASTERISK 

An asterisk icon appears in the message 
box. 

MB-DEFBUTTON1 

First button is the default (the first but- 
ton is always the default unless 
MB_ DEFBUTTON2 or 
MB_ DEFBUTTON3 is specified). 

MB_ DEFBUTTON2 

Second button is the default. 

MB_ DEFBUTTON3 

Third button is the default. 

MB_ APPLMOD AL 

The message box is application modal. 

MB-SYSTEMMODAL 

The message box is system modal. 

Return Value 

Message box returns one of the following values 

depending on the user’s response: 



Message Box Return Values 
Return Value 

IDOK OK button was pressed 
IDCANCEL 

Cancel button was pressed 
IDABORT 

Abort button was pressed 
IDRETRY 

Retry button was pressed 
IDIGNORE 

Ignore button was pressed 
IDYES Yes button was pressed 
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IDNO No button was pressed 

If a message box has a Cancel button, the IDCAN- 
CEL value will be returned if either the Escape or 
Cancel key is pressed. If the message box has no 
Cancel button, pressing the Escape key has no 
effect. 

Notes When a system modal message box is created to 
indicate that the user is low on memory, the 
strings passed as the IpszText and IpszCaption 
parameters should not be taken from a resource 
file, since an attempt to load a resource file may 
fail. The message box can safely use the hand icon 
( MB_HANDICON), since this icon is always 
resident and does not require disk access. 

When the keyboard interface is used to enumerate 
windows, the message box and its parent are con- 
sidered to be next to each other. 

If a message box is created while a dialog box is 
present, use the handle of the dialog box as the 
hwndOwner parameter. 



WinAlarm 



Format 



BOOL FAR WinAl arm (hab , rgfType) 

HAB hab; 

UINT rgfType; 

Description 

This function generates a beep at the system 
speaker. This function returns TRUE if a beep is 
actually generated. rgfType may be one of the fol- 
lowing: 

WA_WARNING 

WA_NOTE 

WA_ERROR 



WinSubstituteStrings 



Format 



INT FAR WinSubstituteStrings (hwnd, IpszSrc, 
IpszDst, cchDstMax) ; 

HWND hwnd; 

LPSTR IpszSrc; 

LPSTR IpszDst; 
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I NT cchDstMax; 

Description 

This function copies a null terminated string from 
*lpszSrc to *lpszDst, performing substitution of 
certain characters with application-supplied 
strings as the string is copied. 

If a string of the form "%<digit>" is encoun- 
tered, where <digit> is a digit from "0" to "9", a 
WM_ SUBSTITUTESTRING message is send to 
the specified window. This message returns a far 
pointer to a null terminated string that is copied 
to the destination, replacing the "%<digit>" 
string. 

If two "%" characters are encountered, only one is 
copied. If the character following the is not a 
digit or both the "%" and the character fol- 
lowing are copied. 

This function returns the length of IpszDst, not 
including the null termination character. If the 
destination string would be longer than cchDstMax 
characters, it is truncated at cchDstMax - 1 char- 
acters; the string is always null terminated. 



WM_ SUBSTITUTESTRING 



Format 



WM_SUBSTITUTESTRING 

LOUINT (lParaml) : INTiString; 

lParam2 : OL; 

Returns : LPSTR IpszSubstituteString; 

Description 

This message is sent by WinSubstituteStringsQ 
when a substitution string of the form 
"%<digit>" is encountered, where <digit> is a 
character between "0" and "9". iString is a 
number between 0 and 9 corresponding to 
<digit>, identifying which substitution is being 
made. 

This message returns a far pointer to a NULL ter- 
minated string, which will be substituted for the 
"%<digit>" string. 

See WinSubstituteStringsQ above. 

Example 

Here is an example of how WinSubstituteStringsQ 
and the WM_ SUBSTITUTESTRING message can 
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be used: 

The call: 

cch = WinSubstituteStrings (hwnd, 

"Do you want to %0 the file %1?" , 
lpchBuffer, cchBuf ferMax) ; 

with the following case in the window procedure of 
hwnd: 

case WM_SUBSTITUTE STRING: 
switch (lParaml) { 
case 0: 

return ( (LPSTR) "delete") ; 
break; 
case 1: 

return ( (LPSTR) "EXAMPLE . EXE " ) ; 
break; 

> 

break; 

produces the string: 

Do you want to delete the file EXAMPLE.EXE? 



4.1.10 Control Windows 

"Control windows", or just "controls", are predefined classes for child win- 
dows that any application can use for input and output. Controls are usu- 
ally part of a dialog box and are loaded from a dialog template, but they 
can also be created by the application by calling WinCreateWindow() with 
the appropriate control class. The following control classes have been 
predefined: 



Standard Control Classes 
Class Name 

WC_ BUTTON 

These controls consist of buttons and boxes that the user can 
select by clicking the mouse or using the keyboard. 

WC-EDIT 

These controls consist of a single line of text that the user 
can edit. 

WC_ STATIC 

These controls are simple display items such as icons and 
text that do not respond to keyboard or mouse events. They 
are used primarily inside dialog boxes. 

WC_ LISTBOX 

These controls present a list of text items from which the 
user can make selections. 
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WC-MENU 

These controls also present a list of items. The items may be 
text or bitmaps, displayed horizontally as "Action Bars" or 
vertically as "Popup Menus". Menus are usually used to pro- 
vide a command interface to applications. 

WC_ SCROLLBAR 

These controls consist of window scroll bars that allow the 
user to make a request to scroll the contents of an associated 
window. 

WC_ MINMAXBOX 

Minimize/Maximize pushbuttons 

WC_ SIZEBORDER 

Window sizing border 

WC_ TITLEBAR 

This control displays the window title or caption and allows 
the user to move its owner by dragging the control. 



4.1.10.1 Common Features 

Control windows are just like any other window, so all of the standard 
window management functions such as WinSetWindowTextQ and 
WinShowWindow() can be used. In addition, they handle the standard 
window messages such as WM_ QUERYWINDOWP ARAMS and 
WM_ ENABLE. See the section on "Window Management". 

Although there are differences among controls of different classes, they all 
share the following common features. 



4-1.10.1.1 Synchronous Painting 

Controls are typically painted synchronously. For more information, see 
"Synchronous Window Updating" 



4.1.10.1.2 Control Identification 

Like all windows, a control has a unique ID value that identifies it. This 
value is determined by the application when the control is created. See 
"Window Attributes". This id is used by the control when it notifies its 
owner. 
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4-1.10.1.8 Control States 

Controls can be enabled and disabled, and hidden and shown with 
WinEnableWindowQ and WinShowWindowQ. A disabled control is usu- 
ally halftoned to indicate to the user that it is disabled. Some controls 
can be hilited by sending them a SETHILITE message. For example a 
titlebar control is hilited by sending it a TBM_ SETHILITE message. 



4 .I.IO.I .4 Control Messages 

Typically, control windows each have a certain set of messages that are 
used to interact with the control. For instance, menu controls will 
respond to window messages to add, insert, and delete menu items. Each 
control has its own set of messages. 



4-1.10.1.5 Control data 

Some controls respond to their control data. They are initially passed the 
control data via the WM_ CREATE message. They have to respond to 
changes to the control data that is sent to them by 
WM_ SETWINDOWPARAMS messages, and return their control data in 
response to WM_ QUERYWINDOWPARAMS messages. 

The following defines the control data for the standard window classes. 

WC_BUTTON 

typedef struct { 

UINT wCheckState; 

UINT wHiliteState; 

> BTNCDATA; 

wChecked is a uint that indicates the current button check state, i.e., the 
same as the value returned by/passed to the 
BM_ QUERY CHECK/BM- SETCHECK message. 

wHiliteState is a uint that indicates the current button hilite state, as 
returned by /passed to BN1_ QUERY/SETHILITE. 

WC_MENU 

ControlData points to a menu template structure. The menu control data 
may not be queried or set after the window is created. The ControlData 
field is interpreted by the menu control only when the control is created. 

WC_EDIT 

typedef struct { 

UINT cchEditLimit; 

> EDITCDATA; 



268 




Window Management Functions 



cchEditLimit contains the maximum number of characters that may be 
entered into the edit control. 

WC_S CROLLBAR 

typedef struct { 

UINT posFirst; 

UINT posLast; 

UINT posThumb; 

> SBCDATA; 

posFirst and posLast reflect the scroll range, and posThumb is the current 
thumb position. 

WC_FRAME 

No control data. 

WC_DIALOG 

No control data. 

WC_T I TLE BAR 

No control data. 

WC_SIZE 

No control data. 

WC_STATIC 

No control data. 

WC_LI STBOX 

No control data. 



4-1.10.1.6 Control Owner Notifications 

When interesting things happen with a control, the owner window of the 
control is notified with a window message. The message sent, and whether 
the message is posted or sent depends on the control. For example, menu 
controls post WM_ COMMAND messages to their owner when an item is 
selected. Many controls send notifications via the WM_ CONTROL mes- 
sage. 
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4-1.10.1. 7 Dialog Codes 

When processing user input, the dialog manager makes some assumptions 
abqut how certain controls operate. For example, when an edit control is 
given the focus, its entire text is selected. 

A control’s "dialog code" contains flags that govern what assumptions the 
dialog manager makes about a control. The dialog manager sends the 
WM_ QUERYDLGCODE message to get a control’s dialog codes. 



4.1.10.1.8 Control Heap 

Most controls require memory for the storage of data associated with that 
control, such as the strings that make up the items in a menu control, or 
the text buffer associated with an edit control. 

This data is normally allocated in a heap created with the Win- 
CreateHeapQ function. Controls typically send a WM_ CONTROLHEAP 
message to tneir owner in order to obtain the heap handle to allocate in. 
Some controls do not require a heap handle; others create their own heap 
handle. 

For each thread with a message queue, there is an associated heap handle 
that can be used by controls (or applications) for the purpose of allocating 
app-specific data. This heap handle is returned when 
WM_ CONTROLHEAP is processed by WinDefWindowProc(). See the 
"Local Memory Manager". 



4.1.10.2 Standard Control Messages 

The following messages can be sent to all controls: 



WM_ AD JUSTWINDOWRECT 



Format 



WM_AD JUSTWI NDOWRECT 
lParaml : LPSWP lpswp 

lParam2 : 0 

Returns: BOOL fAdjusted 

Description 

This message is sent to controls by WinSetWin- 
dowPosQ to allow the control window to adjust its 
new position or size whenever it is about to be 
moved, lpswp points to an SWP structure which 
has been filled in by SetWindowPosQ with the pro- 
posed move/size data. The control may adjust 
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this new position by changing the contents of the 
SWP structure. It can change the x/y fields to 
adjust its new position; it can change the cx/cy 
fields to adjust its new size, or it change the 
hwndlnsertBehind field to adjust its new z-order. 

Frame controls can respond to this message to 
reposition themselves or resize themselves in the 
window frame. Menu controls respond to this mes- 
sage by resizing both their height and width to fit 
the current content of the menu. 

The return value is TRUE if any change has been 
made to the SWP structure, FALSE otherwise. 

When a dialog is created with WinCreateDlgQ or 
WinLoadDlgQ, a WM_ ADJUSTWINDOWRECT 
message is sent to each child window after the win- 
dow is created, with a pointer to an SWP structure 
containing rgf == SWP-SIZE ] SWP-MOVE, and 
the x, y, cx, cy fields initialized to the window’s 
current size and position. The message allows the 
control to adjust its size or position, usually to 
compensate for its border and/or margin. 

The WM_ ADJUSTWINDOWRECT is only pro- 
cessed by listboxes and edit controls: 



Listboxes: 

Listboxes automatically outsets its 
border in addition to changing its height 
to accomodate an exact number of items. 
This means that the "x, y, cx, cy" fields 
in the ,rc file specify the working area of 
the listbox. The border will be drawn 
outside this area. 

Edit controls: 

The edit control, if ES_ MARGIN is 
specified, outsets its margin. This means 
that in the ,rc file, the numbers specified 
as the x, y position of an edit control are 
taken to be the position where the first 
character of text is drawn, not where the 
lower left corner of the surrounding box 
is drawn. Similarly, the height and 
width parameters apply to the editable 
area of the control, thus not including 
the margin. 
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WM_ QUERYDLGCODE 



Format 

WM_QUERYDLGCODE 

lParaml: LPQMSG *lpQmsg; 

lParam2: 0 

Returns: ULONG IDialogCode; 

Description 

When processing user input, the dialog manager 
makes some assumptions about how certain con- 
trols operate. The dialog manager sends the 
WM_ QUERYDLGCODE message to obtain a code 
that govern what assumptions can be made. 

This message is sent by the dialog manager to 
identify the type of control to determine what 
kinds of messages the control will understand, and 
al?o to determine whether an input message may 
be processed by the dialog manager or passed 
down to the control. 

The following information flags (which can be 
OR’ed together) are returned. There are two 
groups of flags: those that identify the type of con- 
trol and the messages that can be sent to it, and 
those that control how the dialog manager handles 
user input: 



Dialog Codes 

Dialog Code 

DLGC_ EDIT 

Identifies an edit control. Assumed to 
understand the EM—SETSEL message. 

DLGC_ BUTTON 

Identifies a button item. Assumed to 
understand the BM_ CLICK message. 

DLGC_ CHECKBOX 

Identifies a checkbox item. Used with 
the DLGC_ BUTTON code. 

DLGC_ RADIOBUTTON 

Identifies a radio button control. Used 
with the DLGC_ BUTTON code. 

DLGC_ STATIC 

Identifies a static control. Static con- 
trols are not included in arrow key 
enumeration. 
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DLGC_ DEFPUSHBUTTON 

Identifies a Default pushbutton control 

DLGC_ UNDEFPUSHBUTTON 

Identifies a Non-default pushbutton 



4.1.10.3 Owner Notification Messages 

Controls are useful because they notify their owners when interesting 
events take place. A control notifies its owner by sending a 
WM_ CONTROL message or by posting a WM_ COMMAND or 
WM—HELP message. 



WM_ CONTROL 



Format 



WM_C0NTR0L 

LOUINT (lParaml) : UINT id 

HIUINT (lParaml) : UINT wNotifyCode 

lParam2: ULONG IControlSpec 

Description 

A WM_ CONTROL message is always sent (via 
WinSendMsgQ.) 

LOUINT(lParaml) contains the window ID of the 
control, which is tne ID parameter of Win- 
CreateWindow() or in a dialog template. 

HIUINT(lParaml) contains what is known as a 
"notification code", which is a value that indicates 
why the notification is taking place. The values of 
the notification codes sent by each control depends 
on the control class. 

lParam2 contains control-specific information, 
which is often simply the window handle of the 
control. 



WM_ COMMAND 



Format 



WM_C0MMAND 

LOUINT (lParaml) : UINT 
LOUINT (lParam2) : UINT 
HIUINT (!Param2) : BOOL 



id 

wSource; 

fMouse; 
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Description 

Menu controls and pushbuttons commonly post 
WM_ COMMAND messages to the message queue. 

IParamI contains the window ID of the control, 
which is the ID parameter of WinCreateWindow() 
or in a dialog template. 

LOUINT(lParam2) contains information that indi- 
cates the source of the WM_ COMMAND message: 



WM_ COMMAND Source Codes 
Source Code 

CMDSRC- PUSHBUTTON 

Posted by a pushbutton control 

CMDSRC- MENU 

Posted by a menu control 

CMDSRC- ACCELERATOR 

Posted by WinTranslateAcceleratorQ. 

CMDSRC- OTHER 

Other source 

HIUINT(lParam2) contains TRUE if the 
\VM_ COMMAND message was posted as a as a 
result of a mouse operation, FALSE if a keyboard 
operation. 



WM-HELP 



Format 



WM_COMMAND 

LOUINT (IParamI) : UINT id 

LOUINT (lParam2) : UINT wSource; 

HIUINT (lParam2) : BOOL fMouse; 

Description 

Menu controls and pushbuttons post WM-HELP 
messages to the message queue when they have 
appropriate style. The implication is that the 
application should respond to the selection of the 
item by displaying help information. Otherwise, 
the message is identical to a WM_ COMMAND 
message. 

IParamI contains the window ID of the control, 
which is the ID parameter of WinCreateWindow() 
or in a dialog template. 

LOUINT(lParam2) contains information that 
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indicates the source of the WM_ HELP message: 



WM_ HELP Source Codes 
Source Code 

CMDSRC- PUSHBUTTON 

Posted by a pushbutton control 

CMDSRC- MENU 

Posted by a menu control 

CMDSRC- ACCELERATOR 

Posted by WinTranslateAccelerator(). 

CMDSRC- OTHER 

Other source 

IIIUINlYlParam2) contains TRUE if the 
WM_ HELP message was posted as a as a result of 
a mouse operation, FALSE if a keyboard opera- 
tion. 



WM_ CONTROLCURSOR 



Format 



LOUINT (lParaml) : UINT idCtl; 

lparam2 : HWND hwndCtl ; 

Returns: BOOL fProcessed; 

Description 

Sent to a control’s owner window when the mouse 
cursor moves over the control window, allowing 
the owner to set the mouse cursor. If FALSE is 
returned, the control will set the cursor as normal. 
If TRUE is returned, the control will not set the 
cursor. 



WM_ CONTROLHEAP 



Format 



WM_CONTROLHEAP 
LOUINT (lParaml) : UINT id 
1 Par am 2: HWND hwndCtl 

Returns : HANDLE hHeap 

Description 

This message is sent by some controls to their 
owner in order to obtain the heap handle to use for 
allocating control-specific data. This message 
should be handled by returning a heap handle to 
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use, which has been created with Win- 
CreateHeapQ. id is the control id, and hwndCtl is 
the window handle of the control. 

WinDefWindowProcQ handles this message by 
returning the queue neap handle. 

See the "Local Memory Manager". 

4.1.11 Static Controls 

Static controls are simple text fields, boxes and rectangles that can be 
used to label, box or separate other controls. Static controls do not accept 
input, nor do they notify their owner. 

A staic control can be disabled, even though it cannot receive input. A 
disabled static control is halftoned. This cab be used to indicate that the 
text is not applicable for some reason. 

Static text items may contain mnemonic characters, which are embol- 
dened. If the text of a static control contains a mnemonic character, the 
text is displayed with the appropriate mnemonic highlighting. 

Static controls can never receive the focus. Whenever a static control 
receives a WM—SETFOCUS message, or whenever the user clicks on a 
static control, that static control advances the focus to the next sibling 
that is not a static control. (Inside dialog boxes, the next non-static con- 
trol will receive the focus.) If the static control has no such siblings, it sets 
the focus to its owner. 



4.1.11.1 Static Control Styles 

There are the following static control styles: 



Static Control Styles 
Style 

SS-TEXT 

Creates a text field. The text is formatted before it is 
displayed. Words that would extend past the end of a line 
are automatically wrapped to the beginning of the next line. 
Variations of the SS-TEXT style are created by ORing vari- 
ous WinDrawTextQ flags into the style. 

The possible flags are: 

DT-LEFT 

Left Justified text 
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DT_ CENTER 

Centered text 

DT-RIGHT 

Right justified text 

DT_TOP 

Text is aligned to top of window 
DT-VCENTER 

Text is aligned vertically in center of window 
DT_ BOTTOM 

Text is aligned to bottom of window 
DT-WORDBREAK 

When specified with DT-TOP, this allows for 
multi-line static text controls, with word wrapping 
at the ends of lines. 

See the WinDrawText() documentation for a more complete 
description of these flags. 

SS_ GROUPBOX 

A groupbox static control is a rectangle that has an identify- 
ing text string in its upper left corner. Group boxes are used 
to collect a group of radio buttons or other controls in a sin- 
gle unit. 

SS-ICON 

Draws an icon. The text of the static control is a string 
which which is used to derive the resource ID from which the 
icon is loaded. The format of the string is: 

1. First byte Oxff, 2nd byte is the low byte of the resource 
ID, 3rd byte is the hi byte of the resource ID. 

2. First character is subsequent characters make up 
the decimal text representation of the resource ID. 

If the string is empty or does not follow the format above, no 
resource is loaded. 

The resource is assumed to reside in the resource file of the 
current process. 

SS_ BITMAP 

Draws a bitmap. The text of the static control names the 
bitmap resource, as for SS-ICON above. 

SS_ FGNDRECT 

Creates a foreground color filled rectangle. 

SS_ BKGNDRECT 

Creates a background color filled rectangle. 
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SS_ FGNDFRAME 

Creates a box with a foreground color frame. 
SS_ BKGNDFRAME 

Creates a box with a background color frame. 



4.1.11.2 Static Notification Codes 

Static items do not generate notification messages. 



4.1.12 Button Controls 

A button control is a small rectangular child window that represents a 
button that the user can turn on or off by clicking it with the mouse. But- 
ton controls can be used alone or in groups, and can either be labeled or 
appear without text. Button controls typically change appearance when 
the user clicks them. 

Buttons can be disabled to prevent them from responding when the user 
clicks on them. Disabled buttons are halftoned. 

The class name to use when creating button controls is WC_ BUTTON. 



4.1.12.1 Button Control Styles 

Button controls have the following window styles: 



Button Control Styles 
Style 

BS_ PUSHBUTTON 

A pushbutton is a box that contains a string. When you 
push a button, the parent window is notified. You push a 
button by clicking the mouse on it or pressing the SPA- 
CEBAR when the button is active. 

BS_ DEFPUSHBUTTON 

A defpushbutton (or default pushbutton) is a pushbutton 
with a thick border box. It has the same properties as a 
pushbutton. In addition, the user may press a defpushbut- 
ton by pressing the RETURN key. 

BS_ CHECKBOX 

A checkbox is a little square with a character string to the 
right. If it is checked, a small black box appears inside the 
little square. When you click the box or string, the checkbox 
changes state and the parent window is notified. You click 
the box by clicking on it with the mouse or pressing the 
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SPACEBAR when it is active. 

BS_ AUTOCHECKBOX 

An automatic check box automatically toggles its state 
whenever the user clicks on it. 

BS_ RADIOBUTTON 

A radio button is similar to a check box, but is typically used 
in groups in which only one button at a time is checked. 
When a radio button is clicked or a cursor key is pressed to 
move within the group, it notifies its owner window. It is 
then up to the owner window to check the clicked radio but- 
ton and uncheck all the rest, if necessary. 

BS_ AUTORADIOBUTTON 

When clicked, an automatic radio button automatically 
checks itself and unchecks all other radio buttons in the 
same group. 

BS_ 3 STATE 

A 3-state check box is identical to a check box control except 
that its check box can be halftoned as well as the box being 
checked or unchecked. 

BS_ AUT03STATE 

An automatic 3-state check box automatically toggles its 
state when the user clicks on it. 

BS-USERBUTTON 

This is a application-definable button. The owner window of 
this style control will receive four additional button mes- 
sages: BN_ HILITE, BN_ UNHILITE, BN_ DISABLE, and 
BN_ PAINT (documented below). 

BS-HELP 

The button posts a WM_HELP message rather than a 
WM_ COMMAND or WM_ SYSCOMMAND message. In 
addition, BS-HELP buttons do not set the focus to them- 
selves when clicked with the mouse. This style is useful for 
producing a button which can be used for selecting help 
information. 



4.1.12.2 Button Control Messages 

Button controls process the following message: 



BM_ CLICK 



Format 



BM_CLICK 
LOUINT (lParaml) 



BOOL fUp; 
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lParam2 : OL 

Returns : OL 

Description 

A button control sent a BM_ CLICK message will 
take whatever action that would occur if the but- 
ton was clicked with the mouse or space bar. If 
fUp is TRUE, then the default upclick action is 
taken; otherwise the default downclick action is 
taken. 



BM_ QUERYCHECKINDEX 



Format 



BM_QUERYCHE CKI NDE X 
lParaml: OL 

lParam2: OL 

Returns: I NT iRadioButton 

Description 

Returns the 0-based index of the checked radio 
button in the same group as the window that sent 
this message, or -1 if none are checked or if the 
button is not a valid radio button. 



4.1.12.3 Button Notification Codes 



4.1.12.8.1 Pushbutton Notification Codes 

When a pushbutton is clicked, a WM_ COMMAND message is posted to 
the owner window. The following information is included in lParaml and 
lParam2 of the WM_ COMMAND message: 



Parameter 

Contents 



lParaml 

Contains the pushbutton control ID 
LOUINT(lParam2) 

Contains the value CMDSRC- PUSHBUTTON 
HIUINT(lParam2) 

Contains TRUE if the command was posted as a result of a 
mouse operation, and FALSE if a keyboard operation. 
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See "Owner Notification Messages" for more information. 



4-1. 12. S. 2 Radio Button and Checkbox Notification Codes 

Radio buttons and check boxes notify their owners with the 
WM_ CONTROL message. 



WM_ CONTROL: Button Notification 



Format 



WM_CONTROL 

LOUINT (lParaml) : UINTidCtl; 

HIUINT (lParaml) : UINT wNotifyCode; 

lParam2: HWND hwndCtl; 

Returns: OL; ' 

Description 

This message is sent to the button control owner 
when a radio button or checkbox is clicked with 
the mouse, or when it receives a BM—CLICK mes- 
sage, or for BS_ USERBUTTON controls. 

LOUINT(lParaml) contains the window ID of the 
button control. HIUINT(lParaml) contains a code 
that indicates the reason for the notification: 



Button Control Notification Codes 
Code 

BN_ CLICKED 

The button has been clicked with the 
mouse or the SPACEBAR is pressed 
when the button has the focus. 

BN_ DBLCLICKED 

The button has been doubleclicked with 
the mouse. 

BN_ PAINT 

The button needs to be painted. 

BN_ HILITE 

The hilited state of the button needs to 
be painted. 

BN_ UNHILITE 

The button should be unhilited. 

BN_ DISABLED 

The button should be painted in a dis- 
abled state. 
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4.1.12.4 Button Control State Messages 

Button controls can be hilited or unhilited. A hilited button is either 
inverted or emboldened. Radio buttons and checkboxes can be checked or 
unchecked. Three state buttons can be checked, unchecked or halftoned. 
WinlsWindowEnabledQ may be used to determine whether or not a button 
is enabled or disabled. 

The button controls may also be modified by the 
WM_ SET/QUERYWINDOWP ARAMS messages. 



BM-SETHILITE 



Format 



BM_SETHILITE 

LOUINT (lParaml) : BOOL fHilite; 

IParami : OL 

Returns: INT fHiliteOld; 

Description 

This message is used to cause the button control to 
be displayed in either the hilited or unhilited 
states. 

Returns the previous hilite state of the button con- 
trol. 



BM_ QUERYHILITE 



Format 



BM_QUERYH I L I TE 
lParaml: 0 

lParam2 : OL; 

Returns: BOOL fHilite; 

Description 

This message returns the current hilite state of the 
button control. Returns TRUE if the button is hil- 
ited, FALSE otherwise. 



BM_ SETCHECK 



Format 



BM_SETCHECK 

LOUINT (lParaml) : wCheck 

lParam2 : OL; 

Returns : wOldCheck ; 
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Description 

This message sets the current check state of the 
button control. Possible state values for a check- 
box or radio button are TRUE (checked) and 
FALSE (unchecked). For three- state checkboxes, 
the possible state values are 0 (unchecked), 1 
(checked), and 2 (indeterminate). Returns the pre- 
vious check state. 



BM_ QUERYCHECK 



Format 



BM_QUERY CHE CK 
lParaml: 0 

lParam2: OL; 

Returns : wCheck ; 

Description 

This message returns the current check state of the 
button control. Returns current check state for 
the button control. Possible state values for a 
checkbox or radio button are TRUE (checked) and 
FALSE (unchecked). For three- state checkboxes, 
the possible state values are 0 (unchecked), 1 
(checked), and 2 (indeterminate). 



4.1.13 Edit Controls 

An edit control is a rectangular window which displays a single line of text 
that the user can edit. When it has the focus, it displays a flashing caret 
to mark the current insertion point. It also allows the user to select parts 
of the text by clicking and dragging the mouse or by using the keyboard 
interface. Selected text can be cut or copied to the clipboard. Text from 
the clipboard can be inserted by pasting from the clipboard. Text which is 
pasted or entered from the keyboard either replaces the current selection 
or is inserted at the insertion point. 

When an edit control is created, an initial buffer of 32 characters is allo- 
cated for it. The user can change this with the EM_ SETTEXTLIMIT mes- 
sage. The initial contents of the edit control can be set with the 
LPCREATESTRUCT parameter passed with the WM_ CREATE message. 

If the user attempts to enter more text in an edit control than specified by 
the text limit set by the EM_ SETTEXTLIMIT message, the edit control 
indicates the error by beeping and does not accept the characters. 
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By default, edit controls use the current SYSTEM font to display charac- 
ters, but the application can direct the control to use another font. 

The class name to use when creating edit controls is WC-EDIT. 

4.1.13.1 Edit Control Styles 

There are the following edit control styles: 



Edit Control Styles 
Style 

ES-LEFT 

The text in the control is left-justified. This is the default 
style if neither ES_ RIGHT or ES_ CENTER are specified. 

ES_ RIGHT 

The text in the control is right-justified. 

ES_ CENTER 

The text in the control is centered. 

ES_ AUTOSCROLL 

Whenever the user tries to move off the end of a line, the 
control automatically scrolls one third the width of the win- 
dow in the appropriate direction. 

ES_ MARGIN 

This style can be used to cause a frame to be painted around 
the control, with a margin around the editable text. The 
margin is 1/2 character width wide, and 1/4 character 
height high. 

If the user attempts to enter more text in an edit control than specified by 
the text limit set by the EM_ SETTEXTLIMIT message, the edit control 
indicates the error by beeping and does not accept the characters. 



4.1.13.2 Edit Control Keys 

Edit controls allow the user to perform the following operations. The 
actual keys used to accomplish these functions are defined by the user 
interface. 

1. Moves caret one character left 

2. Moves caret one character right 

3. Extends selection one character left 
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4. Extends selection one character right 

5. Moves caret one word right 

6. Moves caret one word left 

7. Moves caret to beginning of line 

8. Moves caret to the end of the line 

9. Deletes the character to the left of the caret and resets the current 
selection 

10. Deletes character to the right of caret and resets current selection 

11. Cuts current selection to clipboard 

12. Deletes current selection, but does not copy it to the clipboard 

13. Replaces current selection with text contents of the clipboard 

4.1.13.3 Edit Control Notification Messages 

Edit controls send the following notification codes to their owner. For a 
general description of notifification codes, see the section on Control Win- 
dows. 



Edit Control Notification Codes 
Code 

EN-SETFOCUS 

The edit control received the focus. 

EN-KILLFOCUS 

The edit control lost the focus. 

EN_ CHANGE 

The content of the edit control has changed, and the change 
has been displayed on the screen. 

EN_ SCROLL 

The edit control display is about to scroll horizontally. This 
can happen the application has sent a scroll message to the 
edit control, or because the content of the edit control has 
changed, or the caret has moved, and the edit control must 
scroll to show current caret position. 
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4.1.13.4 Edit Control Messages 

An application can send or post the following messages to an edit control. 
(See the general control message section for a description of messages that 
can be sent to all controls.) An edit control also responds to the 
WM_ SET/QUERYWINDOWP ARAMS messages. 



EM_ GET CHANGEP 
Format 



EM_GETCHANGED 
lParaml: 0 

lParam2 : 0 

Returns; BOOL f Changed 

Description 

Returns the change ("dirty") state of the edit con- 
trol. fChange is TRUE if the text in the edit con- 
trol has changed since the last time it received a 
WM_ QUERY W1NDOWPAR AMS or 
EM_ GETCHANGED message. Otherwise, 
fChange is FALSE. 

Note This message causes the change state of the edit 
control to be set to FALSE. 



E\l_ QUE RN'S EL 
Format 



EM_QUERYSEL 
lParaml: 0 

lParam.2 : OL 

Returns; LOUINT(): INTichMinS.el 

HIUINT () : INT ichMaxSel 

Description 

Get the current selection of an edit control, ich- 
MinSel is the byte offset of the first character in 
the selection, and ichMaxSel is the byte offset of 
first character after the selection. (The current 
selection consists of one or more characters if ich- 
MaxSel > ichMinSel. The current selection con- 
sists of an insertion point if ichMinSel == ichMax- 
Sel. 



EM_ SET 
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Format 

EM_SETSEL 
lParaml: 0 

LOUINT (lParam2) : INT ichMinSel 
HIUINT (lParam2) ; INT ichMaxSel 
Returns : OL 

Description 

Set the current selection to characters within the 
text with byte offsets less than ichMaxSel and 
greater than or equal to ichMinSel. (If ichMinSel 
== ichMaxSel, the current selection becomes an 
insertion point. If ichMinSel == 0 and ichMaxSel 
>= the number of characters in the buffer, the 
entire text is selected.) 



EM-SETFONT 



Format 



EM_SETFONT 

lParaml: HANDLE hFont 

lParam2: OL 

Returns : OL 

Description 

This message sets the edit control font to hFont (a 
Font Handle.) 



EM_ SETTEXTLIMIT 



Format 



EM_SETTEXTLIMIT 

LOUINT (lParaml) : INT cchMax; 

IParami: OL 

Returns : • BOOL f Success 

Description 

This message is used to set the maximum number 
of characters the user may enter into a text field. 
EM_ SETTEXTLIMIT returns a boolean fSuccess 
which is TRUE if the operation was successful, and 
FALSE if there was not enough memory. 

Notes This message is intended only to limit the length of 
lines that result from the user interacting with the 
edit control. This message also limits the length of 
text that can result from sending EM_ PASTE, or 
WM_ SETWINDOWP ARAMS messages. 
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EM_CUT 



Format 



EM_CUT 

lParaml: 0 

lParam2: OL 

Returns : BOOL fSuccess 

Description 

Sends the current selection to the clipboard in 
CF-TEXT format, then deletes the selection from 
the control window. The lParaml and lParam2 
parameters are not used. 



EM_ COPY 



Format 



EM_COPY 

lParaml: 0 

lParam2: OL 

Returns : BOOL fSuccess 

Description 

Sends the current selection to the clipboard in 
CF-TEXT format. The lParaml and lParam2 
parameters are not used. 



EM_ CLEAR 



Format 



EM_CLEAR 

lParaml: 0 

lParam2: OL 

Returns : BOOL fSuccess 

Description 

This message deletes the current selection. 



EM_ PASTE 

Format 



EM_PASTE 
lParaml : 
lParam2 : 
Returns : 



0 

OL 

BOOL fSuccess 
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Description 

Replaces the current selection with text from the 
clipboard. (If the the current selection is an inser- 
tion point, text is inserted.) Text is inserted only if 
the clipboard contains data in CF-TEXT format. 

4.1.14 Listbox Controls 

A listbox control is a window containing a list of items. Each item in a 
listbox contains a text string (0 or more characters) and a handle. The 
text string is usually displayed in the listbox window. The handle may be 
used by the application to refer to other data associated with each item. 
The control allows the user to make selections from the list and notifies 
the owner when interesting events occur. 

A listbox always contains a scroll bar. If the listbox contains more items 
than can be displayed in the listbox window rectangle, the scroll bar is 
enabled. Otherwise, the scroll bar is disabled. (The enabled/disabled state 
of thescroll bar changes dynamically as items are added to and deleted 
from the listbox. 

The maximum number of items in a listbox control is 32767, but most lists 
will be much shorter. 

The class name to use when creating listbox controls is WC_ LISTBOX. 



4.1.14.1 Listbox Control Styles 

A listbox can have combinations of the following styles. 



Style Meaning 
LS-MULTIPLESEL 

The listbox control allows the user to more than one item to 
be selected at any one time. Lists that do not have this style 
allow only a single selection at any one time. 

LS-OWNERDRAW 

The listbox has one or more items that will be drawn by the 
owner. Typically, these items will be represented by bitmaps 
rather than by text strings. 
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4.1.14.2 Listbox Control Notification Messages 

Listbox controls send the following notification codes to their owner. For 
a general description of notifification codes, see the section on Control 
Windows. 



Style Meaning 
LN_ SELECT 

a new selection has been made in the listbox control. 
LOUINT(lParaml) contains the index of the selected (or 
deselected) item. 

LN-SETFOCUS 

The list has received the input focus. 

LN_ KILLFOCUS 

The listbox control has lost the input focus. 

LN_ SCROLL 

The listbox control is about to scroll. 

LN_ DBLCLICK 

The listbox control been doubleclicked in with the mouse. 



WM-DRAWITEM 



Format 



WM_DRAWI TEM 

LOUINT (lParaml) : INT idListbox 

IParami : 01 EAR *lpoi 

Returns BOOL f Dr awn 

idListbox is the window id of the listbox control 
which is sending the notification, lpoi is a pointer 
to an owner item, which has the following struc- 
ture: 

typedef struct { 

HPS hps; 

RECT rcltem; 

INT iltem; 

HANDLE hi tern; 

> 01 ; 

Description 

This notification is sent to the owner of a listbox 
each time an item must be drawn. lpoi->iItem 
contains the item number, and lpoi->hps is the 
hps which should be used for drawing, lpoi- 
>rcltem contains a rectangle that specifies where 
to draw the item. The owner must return TRUE if 
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it actually draws the item, FALSE otherwise. If 
the item contains text, the owner may return 
FALSE and the listbox will draw the item itself. 
(The listbox will draw the item if and only if the 
item contains text and the owner returns FALSE.) 

This message may be used by applications that 
want to create listboxes containing items that are 
not represented by text strings. Since listboxes 
only know how to dray text, this message must be 
sent to the owner to draw other objects. Typi- 
cally, lpoi->hItem will caontain a handle to the 
object to be drawn. 



WM_ MEASUREITEM 



Format 



WM_MEASURE I TEM 

LOUINT (lParaml) : INT idListbox 

lParam2 : 01 FAR *lpoi 

Returns : INT Height 

Description 

This notification also is sent to the owner of a list- 
box containing with LS-OWNERDRAW style. 
When the owner receives this message, it must cal- 
culate the height of the item and return that value. 

Note - All items in a listbox must have the same 
height, which must be greater than or equal to the 
height of the current font. 



4.1.14.3 Listbox Control States 

Listbox controls have only the standard window states. The enabled state 
of a listbox may be obtained with the WinlsWindowEnabledQ function. 



4.1.14.4 Listbox Control Messages 

An application can send or post the following messages to a listbox con- 
trol. (See the general control message section for a description of messages 
that can be sent to all controls.) 



LM_ QUERYITEMCOUNT 
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Format 



LM_QUERYI TEMCOUNT 
lParaml: 0 

lParam2 : OL 

Returns: INT cltem 

Description 

This message returns a count of the number of 
items in the listbox control. 



LM_ INSERTITEM 



Format 



LM_INSERTITEM 

LOUINT (lParaml) : INT iPosition 

IParami LPSTR IpszItemText 

Returns: INT iltemActual 

Description 

This message inserts an item into a list. iPosition 
is the 0-based position in the list where the item 
should be inserted. If iPosition is LIT- END the 
item is added to the end of the list. If iPosition is 
LIT_ SORTASCENDING, it is insertion sorted 
into the list in ascending order. If iPosition is 
LIT- SORTDESCENDING, the item is inserted in 
descending order. IpszItemText is a pointer to the 
string to be used as the item text, iltem is the 
actual position where the item was inserted. 

Notes If the control cannot allocate space to insert the 
item in the list, it will return LIT-MEMERROR. 



LM-SETTOPINDEX 



Format 



LM_SETTOP INDEX 

LOUINT (lParaml) : INT iltem 

Returns: BOOL f Scrolled 

Description 

This message is used to scroll a particular item to 
the top of the listbox, iltem is the index of the 
item to be moved to the top. fScrolled is TRUE if 
the listbox actually had to scroll to move this item 
to the top. fScrolled is FALSE if the item was 
already at the top, or if iltem is not in the list. 
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LM_ QUERYTOPINDEX 



Format 



LM_QUER YTOP I NDEX 






lparaml : 


OL; 




lparam2 : 


OL; 




Returns : 


INT 


iltem; 



Description 

This message is get the index value of the item 
currently at the top of the listbox. 

If there are no items in the listbox, LIT- NONE is 
returned. 



LM_ DELETEITEM 



Format 



LM DELETEITEM 






LOUINT (IParami) : 


INT 


iltem 


lParam2 : 


OL 




Returns : 


INT 


cltemsLeft 



Description 

This message deletes an item from the listbox con- 
trol. iltem is the (0 based) index of the item to be 
deleted. cltemsLeft is the number of items remain- 
ing in the list after the item is deleted. 



LM-SELECTITEM 



Format 



LM_SELECTITEM 

LOUINT (lParaml) : INT iltem 

IParami: BOOL f Select 

Returns: BOOL fSelected; 

Description 

This message sets the selection state of a the 
specified item. If fSelected is TRUE, the item is 
selected, otherwise the item is deselected. 

For single selection listboxes, the previous selec- 
tion is deselected. If iltem is LIT- NONE, no item 
is selected. 

fSelected is TRUE if a selection is actually made, 
and FALSE otherwise. fSelected will be FALSE if 
the caller tries to select an item not in the list or 
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deselects the current selection of a single selection 
listbox with iltem — — LIT- NONE. 

If an item which is not already selected is 
deselected, the selected item does NOT get 
deselected and the message returns FALSE. 



LM_ GETSELECTION 



Format 



LM_GETSELECTION 

LOUINT (lParaml) : INT iltemPrevious; 

IParami: OL 

Returns UINT iltemSelected 

Description 

This message is used to enumerate the selected 
item(s) in a list box. For a single selection listbox, 
this message always returns the index of the 
selected item, or LIT- NONE if no item is selected. 

For multiple selection listboxes, lParaml is the 
previously enumerated selected item. The message 
returns the index of the next selected item, start- 
ing from lParaml. If lParaml is LIT— FIRST, the 
first selected item is returned. 

Returns LIT— NONE after all items have been 
enumerated. 



Example 

The following example shows how to count the 
number of selected items and place their indexes in 
an array: 

iltem = LIT_FIRST; 
cl terns = 0; 

while ((iltem = (int) WinSendMsg (hwndListBox, 
LM_GETSELECTION, iltem, 

OL)) != LIT_N0NE) { 
rgiltems-{cltems+ + )- = iltem; 

> 



LM-SETITEMTEXT 



Format 



LM_SETI TEMTEXT 

LOUINT (lParaml) : UINT iltem; 

lParam2 : LPSTR IpszBuffer; 

Returns: BOOL f Success; 
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Description 

Sets the text of the specified item by copying the 
text from IpszBuffer to the listbox. Returns TRUE 
if successful, FALSE otherwise. 



WM_ SETITEMHEIGHT 



Format 



WM SETITEMHEIGHT 






LOUINT (lParaml) : 


I NT 


NewHeight; 


lParam2 : 


OL; 




Returns : 


OL; 





Description 

This message is used to change the height of the 
items in a listbox. It is easier to send this message 
than to destroy and re-create the listbox with 
items at the new height. 



LM_ QUERYITEMTEXTLENGTH 



Format 



LM_QUERYI TEMTEXTLE NGTH 
LOUINT (lParaml) : UINTiltem 

lParam2: OL 

Returns: I NT cbltem 

Description 

Gets the size in bytes of the text for the specified 
item. Returns 0 if iltem does not exist, or some 
other error occurs. 



LM_ QUER YITEMTEXT 



Format 



LM_QUERYI TEMTEXT 
LOUINT (lParaml) : 
HIUINT (lParaml) : 
lParam2 : 

Returns : 



UINT iltem; 

I NT cbBuffer; 

LPSTR IpszBuffer; 
I NT cchString; 



Description 

Copies the specified item text from the listbox to 
buffer pointed to by IpszBuffer. cbBuffer specifies 
the maximum number of bytes that may be copied 
to the buffer. If cbBuffer is 0, the entire text string 
is copied. 
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The message returns the length of the string 
copied, not including the null termination charac- 
ter. The length uint is overwritten by the string. 

The size of the item can be determined with the 
LM_ QUERYITEMTEXTLENGTH message. 



LM_ SETITEMHANDLE 



Format 



LM_SETITEMHANDLE 

LOUINT (lParaml) : UINT litem; 

lParam2 : HANDLE hltem; 

Description 

Sets the item handle for the specified item to 
hltem. 



LM_ QUERYITEMHANDLE 



Format 



LM_QUERYI TEMHANDLE 

LOUINT (lParaml) : UINTiltem; 

Returns: I NT hltem; 

Description 

Returns hltem, the handle associated with the 
specified item. 



LM_ SEARCHSTRING 



Format 



LM_SE ARCHSTRING 
LOUINT (lParaml) : 
HIUINT (lParaml) : 
lParam2 : 

Returns : 



UINT cmd 
UINT iltemStart; 
LPSTR IpszSearch; 
UINT iltemFound; 



Description 

This message returns the item index of the next 
item whose string matches the string in 
*lpszSearch. All items are enumerated: searching 
wraps around at the end, starting over again at the 
first item. Searching starts at the first item 
AFTER iltemStart; thus the value from a previous 
LM_ SEARCHSTRING message may be used as the 
starting point in order to find the next matching 
item. If iltemStart is LIT_ FIRST, searching starts 
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from the first item in the listbox. 

cmd contains one of the following values that 
specifies how a match is to be found. (These values 
can be combined using the OR operator.) 

LSS_ SUBSTRING 

The item is matched if it contains a sub- 
string that matches *lpszSearch. 

LSS_ PREFIX 

The item is matched if *lpszSearch 
matches the initial characters of the 
item. 

LSS_ CASESENSITIVE 

Corresponding characters must be the 
same case to match. 

Returns LIT-NONE if no match was found. 

Notes To determine whether a matched item is unique, 
send another LM_ FIRSTSTRING message using 
the matched item as a starting point. If a different 
item is returned, the item is not unique. 

4.1.15 Scroll Bar Controls 

Scroll bars are controls that are used to indicate that additional informa- 
tion can be displayed in a window, logically to the left or right for horizon- 
tal scroll bars, logically above or below for vertical scroll bars. The user 
interface for scroll bars allows for scrolling one ’unit’ or one ’page’ at a 
time, or alternately picking up the scroll bar ’thumb’ and sliding it to a 
position in the scroll bar that indicates a logical position in the program. 

If the user holds the mouse or key button down that caused the scroll bar 
action, the messages will auto-repeat at a rate determined by the value of 
the SV_ SBREPEATTIME system value. 

The default position for a vertical scroll bar is aligned to the right edge of 
the frame window, between the application menu and the size box. A hor- 
izontal scroll bar is, by default, aligned to the bottom edge of the frame 
window, between the left edge and the size box. 

A standard scroll bar has a different appearance when disabled, as deter- 
mined by user interface. 

The class value used to identify the scroll bar class is WC_ SCROLLBAR. 
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The standard IDs used to identify the vertical and horizontal scroll bars in 
frame windows are: 



ID Description 

FID-VERTSCROLL 

Vertical scroll control ID 

FID-HORZSCROLL 

Horizontal scroll control ID 

Scroll bars are created with a default resolution of 0 to 100. 



4-1.15.0.1 Scroll Bar Styles 



Style Description 
SBS-HORZ 

Create a horizontal scroll bar 
SBS-VERT 

Create a vertical scroll bar 



4.1.15.1 Scroll Bar Notification Messages 



WM_ VSCROLL 



Format 



WM_VSCROLL 

lParaml : ULONG idCtl; 

LOUINT (lParam2) : int pos; 
HIUINT (lParam2) : UINT cmd; 
Returns : OL 



WM_ HSCROLL 



Format 



WM_HSCROLL 

lParaml: ULONG idCtl; 

LOUINT (lParam2) : int pos; 

HIUINT (lParam2) : UINT cmd; 

Returns : OL ; 

Description 

These two messages are posted to the scroll bar 
owner’s queue by the window manager. idCtl 
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contains the control window id. cmd contains a 
scroll command, which can be one of the following: 

Scroll Commands 

Command 

SB_ LINEUP 

This is sent if the user hits the up or left 
arrow of the scroll bar with the mouse, 
or if the user hits the VK_UP key. 

SB_ LINELEFT 

Save value as SB_ LINEUP, included for 
completeness. 

SB_ LINEDOWN 

This is sent if the user hits the down or 
right arrow of the scroll bar with the 
mouse, or if the user hits the 
VK_ DOWN key. 

SB_ LINERIGHT 

Same value as SB_ LINEDOWN, 
included for completeness. 

SB_ PAGEUP 

This is sent if the user hits the halftone 
area above or to the left of the scroll 
thumb, or if the user hits the 
VK_ PAGEUP key. 

SB-PAGELEFT 

Same value as SB_ PAGEUP, included 
for completeness. 

SB_ PAGEDOWN 

This is sent if the user hits the halftone 
area below or to the right of the scroll 
thumb, or if the user hits the 
VK_ PAGEDOWN key. 

SB-PAGERIGHT 

Same value as SB_ PAGEDOWN, 
included for completeness. 

SB-THUMBTRACK 

If the user grabs hold of the scroll bar 
thumb with the mouse, this is sent every- 
time the thumb position changes. 

SB_ THUMBPOSITION 

If the user grabbed hold of the scroll bar 
thumb with the mouse, this message is 
sent once the user lets go. 
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SB-ENDSCROLL 

Sent when the user has finished scrolling, 
only if the user wasn’t doing an absolute 
thumb positioning. LOUINT(lParam2) 
contains TRUE if the cursor was inside 
the tracking rectangle when the mouse 
button was released, FALSE otherwise. 

LOUINT(lParam2) holds the scroll position only if 
the user was moving the thumb with the mouse 
(SB-THUMBTRACK and 
SB_ THUMBPOSITION). 



4- 1.15. 1.1 Scroll bar control messages 

The following messages may be sent by the application to control or query 
the scroll bar. Scroll bars also respond to the 
WM-SET/QUERYWINDOWPARAM messages. 



SBM_ SETSCROLLBAR 



Format 



SBM_SETSCROLLBAR 
LOUINT (lParaml) : int pos; 

LOUINT (lParam2) : int posFirst; 

HIUINT (lParam2) : int posLast; 

Returns : OL 

Description 

This message is used to set the scroll bar range and 
position information in the scroll bar control. 

LOUINT(lParam2) and HIUINT(lParam2) delimit 
the range information, their values being inclusive. 
lParaml is the position of the thumb within this 
range. If this position is illegal, the thumb will be 
moved to the nearest position within the range. 
The scroll bar is redrawn to reflect these changes. 

The application usually sends this message when 
either it’s initializing a scroll bar or it’s client win- 
dow is changing in size. These are cases when both 
the range and position information need to be sent 
at once. 



SBM_ SETPOS 
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Format 



SBM_SETPOS 

LOUINT (lParaml) : int pos; 
lParam2 : OL 

Returns : OL 

Description 

This message sets the thumb position of the scroll 
bar control. lParaml is the position of the thumb 
within this range. If this position is illegal, the 
thumb will be moved to the nearest position within 
the range. The scroll bar is redrawn to reflect these 
changes. 



SBM_ QUERTPOS 



Format 



S BM_QUERYP 0 S 
lParaml: 0 

lParam2 : OL 

Returns: int pos; 

Description 

This message simply returns the thumb position 
for this scroll bar. 



SBM_ QUERYRANGE 



Format 



SBM_QUERYRANGE 
lParaml : 
lParam2 : 

LOUINT (return) : 
HIUINT (return) : 



0 

OL 

int posFirst; 
int posLast; 



Description 

This message is used to get the scroll range infor- 
mation from the scroll bar control. 
LOUINT(return) and HIUINT(return) delimit the 
scroll bar range. 
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4.1.16 Menu Controls 

A menu control is a small child or popup window that contains a list of 
items. These items can be represented by text strings, separators, bitmaps 
or menu buttons. Menu templates can be loaded as resources and the 
menu can be created automatically when the parent window is created. 
Also, the application can create a menu by calling WinCreate Window with 
a class WCLMENU. The application can build the menu dynamically by 
sending MM_ INSERTITEM messages, etc. An application can alter 
menus by sending messages to it. 

Menus allow you to select one of the items in the list using the mouse or 
the keyboard interface. When you make this selection, the menu notifies 
its parent by posting (PostMsg) a WM_ COMMAND or 
WM_ SYSCOMMAND message and a unique ID representing the user’s 
selection. 

Menus automatically resize themselves as items are added and removed. 
Menus are automatically destroyed when their owner is destroyed. 

Typically, an application has an action bar menu and several popup sub- 
menus. The action bar is normally visible, and is a child window in the 
parent window frame. The popups are normally hidden and become visi- 
ble when selections are made on the action bar. 



4.1.16.1 Action Bar Layout 

The items displayed in an action bar are displayed as follows: 

1. Choices are left-aligned in the action bar. That is, they begin near 
the left side of the window and are adjacent to each other. 

2. Each choice is displayed with a leading and trailing blank. 

3. Choices are listed horizontally but may be reformatted to multiple 
rows as the size of the window in which it is shown is decreased. 

4. The action bar is separated from the panel body by a solid line. 



4-1.16.1.1 Action Bar Appearance Examples 

The following example shows typical content and layout for the action bar 
in an application window: 



] Small Editor 

> 

I Properties Block Search Format Exit 

> 

| GHI Memo 



% 

\ Fl=Help 



More : v 



| Window Title 

< 

| Action Bar 

< full width 

! of window 



302 





Window Management Functions 



January 24, 1986 

MEMO TO : A . B . Curtis 

FROM: D.E. Fitzgerald 

SUBJECT: Growing Households Inventory 

Abe, 

We have just completed the latest households invento 
and it really looks great. It will allow us to maintain 



Figure 4.3 Action Bar 



The next example shows how the action bar is reformatted when the win- 
dow size is decreased. 



| Small Editor [ 

> % < 

] Properties [ Fl=Help J 

| Block Search # < 

| Format Exit j 

> < 

| GHI Memo More : v j 

I I 

J January 24, 1986 | 

i i 

| MEMO TO: A.B. Curtis | 

i FROM: D.E. Fitzge | 

SUBJECT: Growing Hou | 

i i 

i i 

| Abe, | 

I i 

I I 

] We have just complete! 

| and it really looks great [ 

+ + 



Figure 4.4 Reformatted Action Bar 



4.1.16.2 Menu Control Styles 

A menu control can have combinations of the following styles: 



Menu Control Styles 
MS_ ACTIONBAR 

The items in the list are displayed side by side. This style is 
used to implement a Top Level Menu. Menus that do not 
have this style are displayed in one or more columns and are 
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submenus associated with an action bar. 

All menu controls have styles WS-SYNCPAINT and 
WS-PARENTCLIP. 



4.1.16.3 Menu Items 

There are two types of menu items: Submenu and Command items. A 
sub-menu item contains a reference to a sub-menu which will be displayed 
when the user selects that item. A command item contains a value which 
is returned by the menu when the item is selected. 



Field Meaning 
Handle/ID 

If the item is submenu, this field contains the window handle 
of a submenu which is displayed when the item is selected. If 
the item is command, this field contains a unique ordinal 
value identifies the item. 

Display Object 

This object is displayed to represent the item. It can be a 
string, bitmap, separator or menu button. 



4.1.16.4 Menu Item Styles 

A menu item can have combinations of the following styles. 



Menu Item Styles 
Style 

MIS_ SUBMENU 

The item is submenu. When the user selects this type of 
item, a submenu is displayed from which the user must make 
further selection. Items that are not submenu items are 
Command Items. 

MIS_ SEPARATOR 

The display object is a horizontal dividing line. This type of 
item can only be used in popup menus. This type of item 
cannot be enabled, checked, disabled, highlighted or selected 
by the user. The functional object is NULL when this style 
is specified. 

MIS- BITMAP 

The display object is a bitmap. 
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MIS_ TEXT v 

The display object is a text string. 

MIS_ BUTTONSEPARATOR 

The item is a menu button. Any menu may have zero, one or 
two items of this type. These are the last items in a menu 
and are automatically displayed after a separator bar. The 
user can not cursor to these items, but he can select them 
with the mouse or select them with the appropriate key. 

MS-BREAK 

The item is the last one in a row or column. The next item 
is displayed at the beginning of a new row or column. 

MS_ BREAKSEPARATOR 

Same as MS_ BREAK, except that it draws a separator 
between rows or columns. 

MS_ NODISMSS 

If this item is selected, the popup menu containing this item 
should not be hidden before notifying the application win- 
dow. 

MS-SYSCOMMAND 

If this item is selected, the menu notifies the owner by post- 
ing a WM_ SYSCOMMAND message rather than a 
WM_ COMMAND message. 

MS_ OWNERDRAW 

Items with this style are drawn by the owner. 
WM-DRAWITEM and WM_ MEASUREITEM notification 
messages are sent to the owner to draw the item or deter- 
mine its size. 

MS_ HELP 

If the item is selected, the menu notifies the owner by post- 
ing a WM_ HELP message rather than a WM_ COMMAND. 

MS_ STATIC 

This type of item exists for information purposes only. It 
cannot be selected with the mouse or keyboard. 



4-1.16. 4-1 Placing Help selection in Action Bar 

It is recommended that a Help item is put into the Action Bar to provide 
the Mouse user with a means of getting Help on the Action Bar or its 
related client window. The item should read "Fl=Help" and always 
appear at the top right of the action bar. 

The method by which the placement and function of the Fl=Help item is 
achieved in the Menu Bar is as follows: 
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• The item should be the last item in the template for the Menu Bar 
itself. 

• It should not have an associated Pull-Down menu associated with 
it. 

• It should be MIS_ TEXT|MIS_ BUTTONSEPARATOR style and 
the string should be Fl=Help. 

• The MIS_ BUTTONSEPARATOR style will put the item in the top 
right of the menu bar, separated from the other items by a separa- 
tor bar. It can only be used by the Mouse and cannot be cursored 
to from the Keyboard. Note that the Fl key will achieve the same 
function as the menu item for the keyboard button. 



4.1.16.5 Menu Item Attributes 

Menu Items have the following attributes. Applications can get and set 
the state of these attributes by sending MM_ GETITEMSTATE and 
MM_ SETITEMSTATE messages. 



Menu Item Attributes 
Attribute 

MIA_ HILITED 

The state of this attribute is TRUE if and only if the item is 
selected. 

MIA_ ENABLED 

If the state of this attribute is TRUE, the item is enabled 
and can be selected by the user. If the state is FALSE, it is 
disabled and cannot be selected. The item is halftoned. 

MIA_CHECKED 

A checkmark appears next to the item if the state of this 
attribute is TRUE. 



4.1.16.6 Mnemonics and Mnemonic Highlighting. 

A Mnemonic is a single letter which can be typed on the keyboard as a fast 
way of selecting a Text item within a menu. A mnemonic comes into 
operation when the Input Focus is in a Menu window - either the Action 
Bar or one of the Pull-Down menus. The scope of the mnemonic is the 
Input Focus window - so that an action bar and a pull-down can use the 
same mnemonic letter for different actual items. 

Where mnemonics are used, it is strongly suggested that ALL the items 
within one menu window are given a mnemonic letter. The letter chosen 
should be unique for each item within that menu and must occur within 
the text string representing the item. So, for example, if a menu has the 
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items ’Edit’, ’File’ and ’Erase’, the mnemonic letters chosen might be ’E’, 
’F’ and ’R’ respectively. 

Mnemonic letters within menu items are highlighted by means of an 
underscore, which guides the user’s eye. However, after a little use of a 
menu with Mnemonics, the user should be able to select sequences of items 
rapidly directly from the keyboard without even looking at the screen. 

The application defines the mnemonic letter for each item by placing a 
’tilde’ character into the text string, immediately in front of the mnemonic 
character. When the menu is displayed, the tilde characters are not 
displayed and the mnemonic characters are highlit. If it is necessary to 
display a tilde character in a menu item, then the application should put 
’tilde tilde’ into the initial text string. This applies both to items defined 
via resource files and to those defined directly from the application. 

Note that if more than one mnemonic character is defined for a single 
item, the first mnemonic character in the string is accepted. 

Where the mnemonic character is a letter, both lower and upper case char- 
acters are accepted as mnemonics from the keyboard. 



4.1.16.7 Menu Data Structures 



4- 1.1 6. 7.1 Item Data Structure 

When an application queries or sets the item in a menu, it is transfered in 
the following data structure: 

typedef struct -( 

INT iPosition; 

UINT rgfStyle 

UINT id; 

HWND hwndSubMenu ; 

HANDLE hltem; 

> MENUITEM; 

The iPosition field contains the position index. The rgfStyle field contains 
flags that describe the behavior and appearance of the item. The id field 
contains a unique value that identifies the item. hwndSubMenu contains 
the window handle of the submenu associated with the particular item if 
there is one. Otherwise, hwndSubMenu contains 0. For all objects except 
MIS_TEXT, hltem contains a handle to the display object. For Text 
objects, hltem is NULL. The application must send a separate message to 
query or set the item text. 
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4-1.16. 7. 2 Menu Template Data Structure 

Menu templates are data structures that define menus that will be created. 
Menu templates can be loaded as resources or created dynamically. Tem- 
plates loaded as resources can not contain references to bitmaps or owner- 
draw items, shown below. A menu template consists of a sequence of vari- 
able length records. Each record in a template defines an item. If an item 
contains a reference to a submenu, the template that defines that submenu 
is nested after the definition of that particular item. 

typedef struct tagMT 
UINT cmti; 

UINT codepageid; 

MTI rgmti (cmti) ; 

MT; 



cmti contains the count of menu template items, 
codepageid 

is the identifier of the codepage used for the text items 
within the menu (but not any submenus, which each have 
their own codepages). Note that this MUST be 850 for the 
present. 

rgmti is a variable sized array of menu template items (described 
below.) 

typedef struct tagMTI 
UINT rgf Style; 

UINT idltem; 

if (rgf Style AND MIS_BITMAP) 

CHAR szItemString-(?)- ; 
if (rgfStyle AND MI S_0WNERI TEM) 

VOID; 

if (rgfStyle AND MIS_TEXT) 

CHAR szItemString-{?}- ; 
if (rgfStyle AND MI S_SEPARATOR) 

VOID; 

if (rgfStyle AND MIS_SUBMENU) 

MT MenuTemplate; 

MTI; 



rgfStyle contains a combinition of menu item styles (MIS_ *) com- 
bined with the OR operator. 

idltem contains a unique non-negative integer value which identifies 
the item. 

Following idltem is a variable data structure whose format depends upon 
the value of rgfStyle: 
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• If rgfStyle contains MIS-TEXT, it is a O-terminated string. 

• If rgfStyle contains MIS_ BITMAP, it is a O-terminated string. 

For MIS_ BITMAP menu items, the item text string may be used to 
derive the resource ID from which a bitmap will be loaded. There 
are 3 cases: 

1. The first byte is NULL - ie no resource is defined and it is 
assumed that the application will subsequently provide a bit- 
map handle for the item. 

2. First byte is Oxff, 2nd byte is the low byte of the resource ID, 

3rd byte is the hi byte of the resource ID. 

3. First character is subsequent characters make up the 
decimal text representation of the resource ID. 

The resource is assumed to reside in the resource file of the current 
process. 

If the string is empty or does not follow the format above, no 
resource is loaded. 

• If rgfStyle contains MIS_ OWNERDRAW, it is expected that the 
application will subsequently provide a handle to some 
application-defined object for the item. 

• If rgfStyle contains MIS_ SEPARATOR, it is VOID. 

• If rgfStyle contains MIS_ SUBMENU, it contains a complete sub- 
menu data structure (ie a menu template) 



4.1.16.8 Menu Notification Messages 

Menu controls send the following notification codes to their owner. For a 
general description of notifification codes, see the section on Control Win- 
dows. 



Menu Notification Codes 
Code 

WM_ INITMENU 



Format 



WM_INITMENU 

LOUINT (lParaml) : INT idMenu 

lParam2 : HANDLE hwndMenu 

This notification is sent to the owner whenever a 
menu is about to become "active." (The menu win- 
dow is not really activated, and it does not receive 
the focus, it just looks and acts like it is.) This 
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notification is often used to let application change 
the state of menu items before the menu is 
displayed. LOUINT(lParaml) contains the id of 
the menu being initialized ana lParam2 contains 
the menu window handle. 

WM-MENUSELECT 



Format 



WM_MENUSELECT 

LOUINT (lParaml) : UINT idltem; 

HIUINT (lParaml) : BOOL fPostCommand 

1 Par am 2 : HWND hwndMenu 

An item in the menu was selected. In this case, the 
menu posts a WM_ COMMAND or a 
WM_ SYSCOMMAND message to its owner. 
LOUINT(lParaml) contains the ID of the selected 
item. HIUINT(lParaml) contains BOOL 
fPostCommand. lParam2 contains the menu win- 
dow handle. 

If fPostCommand is TRUE, then the item being 
selected will cause a WM_ COMMAND or 
WM_ SYSCOMMAND message to be posted, and 
the menu possibly to be dismissed. This is essen- 
tially a symchronous command notification. If the 
message returns TRUE, then the command will be 
posted as usual, and the menu will be dismissed 
(unless the currently selected item has attribute 
MIS_ NODISMISS.) If FALSE is returned, then no 
message is posted, and the menu is not dismissed. 

WM-DRAWITEM 



Format 



WM_DRAWI TEM 

LOUINT (lParaml) : INT idMenu 

!Param2 : OWNERITEM FAR *lpoi 



idMenu is the window id of the menu control 
which is sending the notification. 

lpoi is a pointer to an owner item, which has 
the following structure: 

typedef struct tagOWNERITEM 
HPS hps; 

UINT rgfStyle; 

RECT rcltem; 

UINT idltem; 

HANDLE hi tern; 
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> OWNERITEM; 

This notification is sent to the owner of a menu 
anytime it is necessary to draw an item that has 
item style MIS_ OWNERDRAW. When the menu 
owner receives this message it is responsible for 
drawing the specified item using hps = lpoi->hps 
inside the rectangle lpoi->rcItem. If the item has 
style MIS_ TEXT, lpoi->hItem is NULL, and the 
owner can get the text for the item by sending a 
MM_ QUERYITEMTEXT message. Otherwise, 
hltem is a handle to a display object that will be 
interpreted by the owner. 

rgfStyle is the same as the style field in the 
MENUITEM data structure. 

WM_ MEASUREITEM 



Format 



WM_MEASURE ITEM 

LOUINT (lParaml) : INT idMenu 

lParam2 : OWNERITEM FAR *lpoi 

This notification also is sent to the 
owner of a menu containing items with 
MIS- OWNERDRAW style. When the 
owner receives this message, it must cal- 
culate the size of the item and store in 
lpoi- >rcItem.xRight and lpoi- 
>rcItem.yTop. The lpoi->rcItem.xLeft 
and lpoi->rcItem.yBottom should not be 
set by the owner. 



4.1.16.9 Menu Control Messages 

An application can send or post the following messages to a menu control. 

See the general control message section for a description of messages that 
can be sent to all controls. 



MM_ STARTMENUMODE 



Format 

MM_ST ARTMENUMODE 

LOUINT (lParaml) : BOOL fMouse 

!Param2: POINT ptMouse 
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Description 

This message is used to begin menu selection. It is 
sent to the menu when the user presses the menu 
key. fMouse is TRUE if a mouse event has caused 
the message. If fMouse is TRUE, ptMouse con- 
tains the initial mouse coordinates. 



MM_ ENDMENUMODE 



Format 



MM_ENDMENUMODE 

Description 

This message is used to end menu selection. When 
the menu receives this it hides the menu window if 
it is a popup window. WM_ CANCELMODE has 
the same effect as MM_ ENDMENUMODE 



MM_ INSERTITEM 



Format 



MM_INSERTITEM 

lParaml: MENUITEM FAR *lpltem 
lParam2 : LPSTR IpszText 

Returns: int iltemActual 

Description 

This message inserts an item into a menu. 



lpltem points to an MENUITEM data structure 
containing the item to be inserted. (This 
data structure includes an iPosition field. 
If iPosition is MIT-END, the item is 
added to the end of the list. 

IpszText 

points to a text string if the item style 
includes MIS_ TEXT. 

iltemActual 

is the actual position where the item was 
inserted. 

Notes If the control cannot allocate space to insert the 
item in the list, it will return MIT_ MEMERROR. 
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MM_ DELETEITEM 



Format 



MM_DELETE ITEM 

LOUINT (lParaml) UINT idltem 

HIUINT ( lParaml) BOOL flncludeSubmenus 

Returns: INT cltemsLeft 

Description 

This message deletes an item from the menu con- 
trol. idltem is the id of the item to be deleted. 
cltemsLeft is the number of items remaining in the 
list after the item is deleted. Any display object or 
submenu referenced by the item is destroyed. 

If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 



MM_ REMOVEITEM 



Format 



MM_REMOVE ITEM 

LOUINT (lParaml) UINT idltem 

HIUINT ( lParaml) BOOL flncludeSubmenus 

Returns: INT cltemsLeft 

Description 

Same as MM_ DELETEITEM, except does not des- 
troy the display object or submenu. 



MM-SELECTITEM 



Format 



MM_SELECTITEM 
LOUINT (lParaml) 
HIUINT (lParaml) 
LOUINT (lParam2) 
HIUINT (lParam2) 
Returns : 



UINT idltem 
BOOL flncludeSubmenus 
BOOL fSelected 
BOOL fDismiss 
BOOL fSuccess 



Description 

This message sets the selection state of the 
specified item, if fDismiss is TRUE, then 
WM_ SYS COMMAND or WM_ COMMAND is 
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posted, and the menu is dismissed, if the item is 
not MIS_ NODISMISS. If fSelected is TRUE, the 
item is selected. If fSelected is FALSE, the item is 
deselected. fSuccess is TRUE if a selection is actu- 
ally made, and FALSE otherwise. 

The application can set the selection to NULL by 
setting idltem = MIT-NONE, in which case fSuc- 
cess will be TRUE. 

If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 



MM_ GETSELITEMID 



Format 



MM_GETSELITEMID 
lParaml: OL; 

lParam2: OL; 

Returns UINT idltemSelected 

Description 

This message returns the ID of the currently 
selected item (even if in a submenu.) 



MM_ QUERYITEM 



Format 



MM_QUERYI TEM 

LOUINT (lParaml) : UINT idltem 

HIUINT (lParaml) : BOOL flncludeSubmenus 

lParam2 : MENUITEM *lpltem 

Description 

Copies the specified item from the menu to the 
buffer pointed to by lpltem. 

If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 
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Note This message does not retrieve the text for items 
with style MIS_ TEXT. The application must use 
MM_ QUER YITEMTEXT . 



MM_ QUERYITEMTEXT 



Format 



MM_QUERYI TEMTEXT 

LOUINT (lParaml) : UINT idltem 

HIUINT (lParaml) : INT cchBufferMax 

lParam2 : LPSTR IpszBuffer 

Description 

This message gets the text string which is used for 
a menu item’s display object, if it has style 
MIS_ TEXT. 



idltem is the item id 
cchBufferMax 

specifies the size of the buffer. 

IpszBuffer 

points to the buffer to receive the zero 
terminated string. 



MM_ QU ERYITEMTEXTLENGTH 
Format 



MM_QUERYI TEMTEXTLENGTH 

LOUINT (lParaml) : UINT idltem 

Returns INT cchltem 

Description 

Returns the length of the text string for 
MIS_ TEXT items, not including the NULL termi- 
nator. Returns 0 if not MIS-TEXT. 



MM_ SETITEMHANDLE 



Format 



MM_SETI TEMHANDLE 

LOUINT (lParaml) : UINT idltem 

IParami : HANDLE hltemNew 

Description 

This message is used to change the bitmap or han- 
dle of a non-MIS_ TEXT item, idltem is the item 
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Id, and hltemNew contains the handle to the new 
display object. 



MXLSETITEMTEXT 



Format 



MM_ SETITEMTEXT 

LOUINT (lParaml) : UINT idltem 

IParami : LPSTR IpszText 

Description 

This message is used to change the text string 
display object for items with style MIS-TEXT. 



IpszText 

points to a zero terminated text string to 
be used as the new display object. 



MM_ SETITEM 



Format 



MM_SETITEM 

HIUINT (lParaml) : BOOL flncludeSubmenus 
lParam2: MENUITEM *lpltem 

Description 

This message copies the contents of *lpltem to the 
menu item with the same id. 

If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 



MM_ ITEMPOSITIONFROMID 



Format 



MM_ITEMPOSITIONFROMID 

LOUINT (lParaml) : UINT idltem 

HIUINT (lParaml) : BOOL flncludeSubmenus 

Returns: INT iPosition 

Description 

Given the ID of an Item, this message returns the 
(0 based) position of the item in the menu. If there 
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is no item in the menu with this id, the message 
returns MT_ NONE. 

If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 



MM_ ITEMIDFROMPOSITION 



Format 



MM_ITEMIDFROMPOSITION 

LOUINT (lParaml) : INT iPosition 

Returns: UINT idltem 

Description 

Given the position, this message returns the ID of 
the item at that position. If the position is not a 
valid position, this message returns MIT_NONE. 



MM_ QUERYITEMCOUNT 



Format 



MM_QUERYI TEMCOUNT 
Returns: int cltem 

Description 

This message returns a count of the number of 
items in the menu control. 



MM_ QUERYITEMATTR. 



Format 



MM_QUERYI TEMATTR 
LOUINT (lParaml) : UINT 

HIUINT (lParaml) : BOOL 
LOUINT (lParam2) UINT 

Returns : UINT 



idltem 

flncludeSubmenus 

rgfAttributeMask 

rgfState 



Description 

Get the current state of the attributes of menu 
item, idltem is the ID of the item. rgfAttribu- 
teMask is a bit mask indicating the attribute 
values to get. Returns the current state values 
that correspond to the state mask. 
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If flncludeSubmenus is TRUE, and if the window 
which receives this message does not have an item 
with the specified id (idltem), the submenus of this 
menu will be searched for an item with a matching 
id. If a match is found, the operation will be per- 
formed on the submenu. 



MM_ SETITEMATTR 



Format 

MM_SETI TEMATTR 

LOUINT (lParaml) : UINT idltem 

HIUINT (lParaml) : BOOL flncludeSub’ 



4.1.17 Caret Manager 

This section describes the functions used to create, display, move, and des- 
troy the system caret. The system caret is a rectangle that can be moved 
to any location on the display screen. The caret is typically used in text 
applications to mark the location where characters will be inserted. 

The size and position of a caret are specified in window coordinates, rela- 
tive to the window that the caret is in. 

The caret is clipped in a window as with all other drawing to that window. 
The caret is automatically hidden and shwon by WinScrollWindowQ, hid- 
den by WinBeginPaintQ, and shown by WinEndPaintQ. 



4.1.17.1 Caret Data Structures 

typedef struct { 

HWND hwnd; 

INT x, y; 

INT cx, cy; 

UINT rgf; 

INT iHideLevel; 

> CARETINFO; 



4.1.17.2 Caret Routines 



WinCreateCaret 



Format 
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INT x; 

INT y; 

INT cx; 

INT cy; 

UINT rgf; 

Description 

This function creates a caret for window defined by 
hwnd. The caret has its position defined by the coor- 
dinates x and y, its size by cx and cy. These coordi- 
nates are in window coordinates, relative to hwnd. 

The rgf parameter specifies the appearance of the 
caret, and whether the cx and cy parameters are inter- 
preted. 

The appearance of the caret is specified by rgf. This 
flag can be any combination of the first 5 of the follow- 
ing flagss. The last flag bit is used to set the position 
of the caret. 

Returns TRUE if successful, FALSE otherwise. 



Caret flag bits 
Value 

CARET- SOLID 

The caret is solid. 

CARET- HALFTONE 

Create a halftone caret. 

CARET- RECT 

Solid rectangular caret. 

CARET- FRAME 

Rectangular frame. 

CARET- FLASH 

The caret flashes. 

CARET- SETPOS 

Set a new caret position, cx and cy are 
ignored. Used when a caret has already been 
created. 

If cx or cy is 0, then the system nominal border width 
or height is used. These values can be obtained by cal- 
ling WinGetSysValue with SV-CXBORDER and 
SV-CYBORDER as indexes. The width of a text 
caret is usually set to 0. This is preferable to giving 1 
as the cx argument, since on a high resolution device a 
width of 1 may produce a very thin line. 

If the flag CARET- SETPOS is specified the caret 
must already exist and size and appearance flags are 
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ignored. 

The caret is initially hidden. The WinShowCaret 
function must be called to display the caret. 

Only one caret is available at a time, so it is not possi- 
ble to have two carets flashing. An applications 
should create a caret only when it has the keyboard 
focus or is the active window. Creating carets at other 
times may stop the caret from flashing in another 
application. Similarly, when an application becomes 
inactive or loses the focus, its caret should be des- 
troyed. 



WinDestr oyCaret 

Format 



BOOL WinDestroyCaret (hwnd) 

HWND hwnd; 

Description 

This function destroys the current caret, if it belongs 
to the specified window. Has no effect if the caret does 
not belong to hwnd. 

Returns TRUE if successful, FALSE otherwise. 



WinShowCaret 



Format 



I NT WinShowCaret (hab, hwnd, fShow) 

HWND hwnd; 

BOOL fShow; 

HAB hab; 

Description 

This function displays (fShow is TRUE) or removes 
(fShow is FALSE) a caret created with the Win- 
CreateCaret function in the same window specified by 
hwnd. 

If the caret has been removed several times without 
any intervening calls to display it, an equal number of 
WinShowCaret calls with fShow being TRUE must be 
made before the caret is redisplayed. 

This function returns the caret show level, after the 
caret is shown or hidden. Returns iHideLevel, which is 
0 if the caret is visible, 1 or greater if the caret is hid- 
den. 
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WinQueryCaretlnfo 



Format 



BOOL WinQueryCaretlnfo (hab, lpCaretlnfo) 

HAB hab; 

CARETINFO FAR * lpCaretlnfo ; 

Description 

Information about the current caret is returned in 
♦lpCaretlnfo. The fields of this structure correspond 
to the parameters to WinCreateCaretQ, except that 
the rgf field never includes the CARET— SETPOS bit. 

The size and position of the caret are returned in win- 
dow coordinates relative to lpCaretInfo->hwnd. 

Returns TRUE if a caret exists, FALSE otherwise. If 
no caret exists, *lpCaretInfo is not changed. 

iHideLevel is a variable that is incremented by 
WinShowCaretfhwnd, FALSE) and decremented by 
WinShowCaret(hwnd,TRUE). The caret is visible only 
if iHideLevel is 0. 



4.1.18 Mouse Cursor 

This section describes the functions that affect the mouse cursor pointing 
device. 

The appearance of the cursor is defined by a bitmap. The bitmap must be 
a certain size, defined by the system. There are two possible sizes: the sys- 
tem cursor size, and the system icon size. These values may be obtained 
with GetSysValue(). 

The bitmap is always twice as tall as either the system cursor or system 
icon size. The bitmap is divided into two parts: the XOR mask and the 
AND mask. The cursor or icon is drawn by first ANDing the screen with 
the top half of the bitmap, and then XORing with the bottom half of the 
bitmap. 



4.1.18.1 Mouse Cursor Data Structures 

A cursor is identified by a "cursor handle": 
typedef HANDLE HCURSOR; 
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The CURSORINFO data structure describes a cursor: 

typedef struct { 

I NT xHotspot; 

I NT yHotspot; 

HB I TMAP hbmCur sor; 

> CURSORINFO; 

The hbmCursor field is a bitmap handle to be used for the cursor image. 
The 

The xHotspot and yHotspot fields are the position within the the cursor of 
the "hot spot". This might be the tip of an arrow cursor, or the center of a 
crosshair cursor. 



WinLoadCursor 



Format 



HCURSOR WinLoadCursor (hab, idModule, idCursor) 
UINT idModule; 

UINT idCursor; 

HAB hab; 

Description 

This function loads the cursor resource identified by 
idCursor from the file associated with the module 
specified by hlnstance. Returns a cursor handle if suc- 
cessful, NULL otherwise. 

If idModule, returned by the DOS DosLoadModule, is 
NULL, the cursor is loaded from the application’s 
resources. Otherwise, idModule is a module handle of 
a dynamic-link library that contains cursor resources. 

Notes A new copy of the cursor is created each time Win- 
LoadCursorQ is called. The cursor handle must be 
destroyed with WinDestroyCursor(). 

To obtain one of the standard system cursors, use Get- 
SysValueQ. The standard system cursors must not be 
freed by the application. 



WinCreateCursor 



Format 



HCURSOR WinCreateCursor (hbmCursor, f Cursor, 
xHotspot, yHotspot) 

HBITMAP hbmCursor; 

BOOL f Cur sor; 

I NT xHotspot, yHotspot; 
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Description 

This function creates a cursor from the specified bit- 
map handle and the hotspot values. If fCursor is 
TRUE, the bitmap is stretched to have the system cur- 
sor dimensions. If fCursor is FALSE, the bitmap is 
stretched to have the system icon dimensions. 

Returns a cursor handle, or NULL if unsuccessful. 



WinDestroyCursor 



Format 

BOOL WinDestroyCursor (hcsr) 
HCURSOR hcsr; 

Description 

This function destroys a cursor or icon. 



WinSetCursor 



Format 



HCURSOR WinSetCursor (hab, hcsr) 

HCURSOR hcsr; 

HAB hab; 

Description 

This function sets the mouse pointer cursor to the 
specified cursor Returns the previous cursor handle, or 
NULL if none existed. If hcsr is NULL, the cursor is 
removed from the screen. 

Notes This function is very fast if hcsr is the same as the 
current cursor handle. 



WinShowCursor 



Format 



I NT WinShowCursor (hab, fShow) 

HAB hab; 

BOOL fShow ; 

Description 

This function is used to show or hide the mouse cur- 
sor. 

Visibility of the mouse cursor is controlled by the 
mouse cursor level. If the cursor level is <= 0, then 
the mouse cursor is visible; if > 0, then the cursor is 
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invisible. 

If fShow is TRUE, then ShowCursorQ decrements the 
cursor display level. If the cursor level is decremented 
to 0, then the mouse cursor is shown. 

If fShow is FALSE, the cursor level is incremented. If 
it is incremented to 1, the mouse cursor is hidden. 

ShowCursorQ returns the new cursor level. 

Notes The initial value of the cursor level depends on 

whether a mouse is installed in the system or not. If a 
mouse exists, the cursor level is 0 (cursor is visible), 
otherwise, the cursor level is 1 (cursor is invisible). 

To obtain the current cursor display level, use 
GetSysV alue(SV_ CURSORLEVEL). 



WinSetCursorPos 



Format 



BOOL WinSetCursorPos (hab, x, y) 

HAB hab; 

INT x, y; 

Description 

This function sets the position of the mouse cursor to 
the screen coordinates x and y. Returns TRUE if suc- 
cessful, FALSE otherwise 



WinGetCursorPos 



Format 



BOOL WinGetCursorPos (hab, lppt) 

HAB hab; 

LPPOINT lppt; 

Description 

This function returns the current mouse pointer posi- 
tion, in screen coordinates, in *lppt. The position 
returned is the true position at the time GetCursorPos 
was called; this function is NOT synchronized with the 
WinGetMsgQ and WinPeekMsgQ functions. Use 
WinGetMsgPosQ to get the mouse position of the last 
message obtained via WinGetMsgQ or WinPeekMsg(). 
Returns TRUE if successful, FALSE otherwise. 
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WinRestrictCursor 



Format 



BOOL WinRestrictCursor (hab, lprc) 

HAB hab; 

LPRECT lprc; 

Description 

This function is used to restrict the mouse cursor to 
the rectangle indicated by lprc. lprc is assumed to 
point to a rectangle in screen coordinates. If lprc is 
NULL, then the, entire screen is assumed. Returns 
TRUE if successful, FALSE otherwise. 



WinQueryCursorlnfo 



Format 



BOOL WinQueryCursorlnfo (hcsr, lpCursorlnfo) 
HCURSOR hcsr; 

CURSORINFO FAR * lpCursorlnfo; 

Description 

This function is used to obtain a cursor’s bitmap han- 
dle and hotspot coordinates. This information is 
placed in *lpCursorInfo. Returns TRUE if successful, 
FALSE otherwise. 



4.1.19 Clipboard Manager 

The Clipboard Manager maintains data to be used for data interchange 
using the Cut/Copy/Paste editing metaphor. A set of functions is pro- 
vided to allow applications to easily implement these commands, in such a 
way that data may be transferred from one application to another. 



4.1.19.1 Cut/Copy/Paste Editing Metaphor 

The Cut, Copy, and Paste commands work as follows: 



Command 

Description 

Copy Copies the current selection into the clipboard. The previous 
contents of the clipboard are destroyed. 
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Cut Deletes the current selection, after first copying it into the clip- 
board. The previous contents of the clipboard are destroyed. 

Paste The current selection is deleted, then a copy of the contents of 
the clipboard is inserted at the selection. The clipboard is not 
changed. 

Clear Same as Cut, except that the selection is not copied to the clip- 
board. The clipboard is not changed. 

Notice that these commands operate on the contents of the clipboard and 
the current selection. Logically, there is only one item of data in the clip- 
board at a time: a selection. 

A selection may be placed into the clipboard in a variety of formats. 

These formats may be defined by the application, or one of the predefined 
standard clipboard formats may be used. A format is identified by a 16- 
bit value. Like window messages, format values may be registered dynam- 
ically that are guaranteed to be unique across the system. 

In order to facilitate transferring data to a wide variety of applications, 
the selection may be copied to the clipboard in more than one format. 
When an application obtains data from the clipboard for a Paste com- 
mand, it can request the data in whatever format is most convenient. 

Clipboard data does not need to be generated, or "rendered", at the time 
it is placed in the clipboard. Instead, the application renders the data at 
the time another application requests the data for a Paste operation. 
Because it often takes a considerable amount of time and memory to 
render a selection in the many formats that an application may be capable 
of producing, this "delayed rendering" feature is quite useful. 

The clipboard is "owned" by the window that last issued the Win- 
SetclipbrdOwnerQ function. There may be data in the clipboard even if 
the clipboard is unowned, such as when an owner window is destroyed. 
When clipboard data is requested for a Paste that hasn’t been rendered 
yet, the clipboard owner window is sent a message to render it. 

It is not always necessary to own the clipboard when putting data into it. 
It must be owned in the following circumstances: 

— If delayed rendering is used, so that the owner can process the 
WM-RENDERFMT messages 

— If any data with the CFI_ OWNERDISPLAY flag has been set so that 
the owner can process the WM-PAINTCLIPBOARD, 

WM_ SIZECLIPBOARD, WM_ HSCROLLCLIPBOARD, and 
WM_ VSCROLLCLIPBOARD messages 

— If any data with the CFI- OWNERFREE flag has been set, so that the 
owner can process the WM—DESTROYCLIPBOARD message 

In any of the cases above, the owner must not terminate until the 
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WM_ DESTROY CLIPBOARD message has been processed. 

In order to access the clipboard, it must be opened. When a thread has 
opened the clipboard, other threads are not allowed access to the clip- 
board. Closing the clipboard allows other threads to access the clipboard. 
Once data has been set into the clipboard, the program that set the data 
should not change it. 

Generally, clipboard operations should be performed only as a direct or 
indirect result of some user operation. 

It is possible for an application to register a window as a "Clipboard 
Viewer" window. This window is responsible for displaying the contents 
of the clipboard. It is notified of changes to the clipboard by being sent 
certain window messages when the clipboard changes. Only one window 
at a time may be registered as the clipboard viewer. 

The clipboard viewer can display any of the standard clipboard formats. 
However, since the clipboard viewer cannot display data that has not been 
rendered yet, there are a few special predefined clipboard formats that are 
used for clipboard viewer display purposes only, if any of these special 
formats exist in the clipboard, the clipboard viewer will display these for- 
mats rather than attempt to display the others. These are the 
CF_ DSPTEXT and CF-DSPBITMAP formats defined below. 

To display private clipboard formats, the clipboard viewer application 
may send messages to the clipboard owner window to draw the clipboard. 



4.1.19.2 Standard Clipboard Formats 



Standard Clipboard Formats 
Format 

CF-TEXT 

Text format. Each line ends with a carriage return/linefeed (CR- 
LF) combination. Tab characters separate fields within a line. 

A NULL character signals the end of the data. 

CF_ BITMAP 

Bitmap as defined by the BITMAP data structure. 

CF_ DSPTEXT 

Text display format associated with private format. 

CF_ METAFILE 

Metafile format, as defined in the GPI metafile section. The clip- 
board viewer will display this format in preference to privately 
formatted data. 
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CF-DSPBITMAP 

Bitmap display format associated with private format. The clip- 
board viewer will display this format in preference to privately 
formatted data. 

In addition to the above predefined formats, any format value registered 
through the standard system atom manager can be used as the fmt param- 
eter. 



4.1.19.3 Clipboard Functions 



WinOpenClipbrd 



Format 



BOOL WinOpenClipbrd (hab) 

HAB hab; 

Description 

This function opens the clipboard for use, preventing 
other threads or processes from examining or changing 
the clipboard contents. If another thread or process 
has the clipboard open, this function does not return 
until it is closed. Returns TRUE if clipboard was suc- 
cessfully opened. 

Messages may be received from other threads or 
processes. 



WinCloseClipbrd 



Format 



BOOL WinCloseClipbrd (hab) 

HAB hab; 

Description 

This function closes the clipboard, allowing other 
applications to open the clipboard with WinOpen- 
ClipbrdQ. Returns TRUE if successful, FALSE other- 
wise. 



WinEmpt yClipbrd 

Format 



BOOL WinEmptyClipbrd (hab) 
HAB hab; 
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Description 

This function empties the clipboard and frees handles 
to data in the clipboard. Returns TRUE if sucessful, 
FALSE otherwise 



WinSetClipbrdOwner 



Format 



WinSetClipbrdOwner (hab, hwnd) 

HWND hwnd; 

HAB hab; 

Description 

This function sets the current clipboard owner window 
to hwnd. The owner window receives the 
WM_ RENDERFMT, WM_ DESTROYCLIPBOARD, 
and WM_ SIZECLIPBOARD, 

WM_ VSCROLLCLIPBOARD, 
WM-HSCROLLCLIPBOARD, and 
WM_ PAINTCLIPBOARD messages at the appropri- 
ate times. 



WinQueryClipbrdOwner 



Format 



HWND WinQueryClipbrdOwner (hab, fLock) 

HAB hab; 

BOOL fLock; 

Description 

This function returns the window handle of the 
current clipboard owner, or NULL if the clipboard is 
not owned. If fLock is TRUE, then the window handle 
is locked before returning. 



WinSetClipbrdData 



Format 



HANDLE WinSetClipbrdData (h, fmt, rgfFmtlnfo) 
HANDLE h; 

UINT fmt; 

UINT rgfFmtlnfo; 

Description 

This function sets data of the specified format into the 
clipboard, h is a handle to a data object of the format 
specified by fmt. If h is NULL, then the clipboard 
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owner window will be sent a WM_RENDERFMT mes- 
sage to render the format if WinQueryClipbrdData() is 
called with the specified format. 

rgfFmtlnfo contains one of the following flags that 
describe the type of the data handle: 



CFI_ SELECTOR 

Handle is a segment, freed with Dos- 
FreeSeg(). The segment must be allocated 
shareable 

CFI_ OWNERFREE 

Handle is not freed by WinEmptyClip- 
boardQ. The application must free the data 
if neccessary. 

CFI_ OWNERDISPLAY 

This flag indicates that the format will be 
drawn by the clipboard owner in the clip- 
board viewer window via the 
WM_ PAINTCLIPBOARD message. The h 
parameter should be NULL. 

Note that if there is previous data in the clipboard, 

then it is freed by this call. 



WinQueryClipbrdData 



Format 



HANDLE WinQueryClipbrdData (hab, fmt) 

HAB hab; 

UINT fmt; 

Description 

This function returns the clipboard data handle of the 
format indicated by fmt, or NULL if that format does 
not exist in the clipboard. 

Notes The returned data handle must not be accessed after 
WinCloseClipbrd() is called. For this reason, the 
application must either copy the data for long term 
use or process the data before WinCloseClipbrd() is 
called. The application should not free the data han- 
dle or leave it locked. 



WinEnumClipbrdFmts 
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Format 



UINT WinEnumClipbrdFmts (hab, fmtPrev) 

HAB hab; 

UINT fmtPrev; 

Description 

This function is used to enumerate all the formats 
available in the clipboard. If fmtPrev is 0, then the 
first available format is returned. Otherwise, fmtPrev 
should be set to the last format returned, in which 
case WinEnumClipbrdFmtsQ will return the next 
available format. Enumeration is complete when 
WinEnumClipbrdFmts() returns 0. 

Example 

The example below counts the number of available for- 
mats, and fills an array with the format values: 

fmt — 0; 
cFmts = 0; 

while ((fmt = WinEnumClipbrdEmts ( fmt) ) != 0) { 

rgfmt [cFmts++] = fmt; 

> 



WinQueryClipbrdF mtlnfo 



Format 



BOOL WinlsClipbrdFmtAvail (hab, fmt, lprgfFmtlnfo) 
HAB hab; 

UINT fmt; 

UINT FAR * lprgfFmtlnfo; 

Description 

This function returns TRUE if data of the format indi- 
cated by fmt is available, FALSE otherwise. This 
function does NOT cause the data to be rendered. If 
TRUE is returned, the format information (CFI_ * 
flags) is returned in ^lprgfFmtlnfo. 



4.1.19.4 Clipboard messages 



WM_ RENDERFMT 



Format 



WM_RENDERFMT 
L0UINT (lParaml) 
!Param2 : 



UINT fmt; 
0L 



331 




Windows Presentation Manager Reference 



Returns : OL 

Description 

This message is a request to the clipboard owner to 
render the data of the format specified in IParaml. 
The data should be rendered into a global handle, 
which should then be set into the clipboard with Win- 
SetClipbrdDataQ. 



WM_ RENDERALLFMTS 



Format 



WM_RENDERALLFMTS 
IParaml: 0 

lParam2: OL 

Returns : 0 

Description 

This message is sent to the application that owns the 
clipboard when the application is being destroyed. 

The application should render the clipboard data in all 
formats it is capable of generating and pass a handle 
to each format to WinSetClipbrdData. This ensures 
that the data in the clipboard can be rendered even 
though the application has been destroyed. 



WM_ DESTROYCLIPBOARD 



Format 



WM_DE STROYCLIPBOARD 
IParaml: 0 

lParam2 : OL 

Returns : 0 

Description 

This message is sent to the clipboard owner when the 
clipboard is emptied through a call to WinEmp- 
tyClipbrd(b If there is any data that has been set 
with the CFI_ OWNERFREE flag, the clipboard owner 
must free the data at this time. 



WM_ PAINTCLIPBOARD 



Format 



WM_PAI NTCL IP BOARD 

IParaml : HWND hwndViewer ; 

lParam2 : PAINTSTRUCT FAR *lpPaintStruct; 
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Returns : OL ; 

Description 

This message is sent when the clipboard contains a 
data handle with the CFI_ OWNERDISPLAY informa- 
tion flag set (i.e., the clipboard owner is responsible for 
displaying the clipboard contents) and the clipboard 
application’s client area needs repainting. The 
WM_ PAINTCLIPBOARD message is sent to the 
owner of the clipboard to request repainting of all or 
part of the clipboard application’s client area. 

IParamI is a handle to the clipboard application win- 
dow. 

lParam2 is a long pointer to a PAINTSTRUCT data 
structure defining what part of the client area to 
paint. 

Notes To determine whether the entire client area needs 

repainting or just a portion of it, the clipboard owner 
must compare the dimensions of the drawing area 
given in the repaint field of the PAINTSTRUCT struc- 
ture to the dimensions given in the most recent 
WM_ SIZECLIPBOARD message. 



WM_ SIZECLIPBOARD 



Format 



WM_S I ZE CL I P BO ARD 

IParamI : HWND hwndViewer ; 

lParam2 : RECT FAR *lprcPaint; 

Returns : OL 

Description 

This message is sent when the clipboard contains a 
data handle for the CF_ OWNERDISPLAY format 
(i.e., the clipboard owner is responsible for displaying 
the clipboard contents) and the clipboard application 
window has changed size. 

IParamI is a handle to the clipboard application win- 
dow. ord lParam2 is a pointer to a RECT 

data structure specifying the area in which the clip- 
board owner should paint. 

Notes A WM_ SIZECLIPBOARD message is sent with a 

pointer to an empty rectangle (0,0, 0,0) as the new size 
when the clipboard application is about to be des- 
troyed or made iconic. This permits the clipboard 
owner to free its display resources. 
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WM_ HSCROLLCLIPBOARD 



Format 



WM_HSCROLLCLI PBOARD 
lParaml : HWND hwndViewer ; 

LOUINT (lParara2) : INT posScroll; 
HIUINT (lParam2) : INT codeScroll; 
Returns : OL 



WM_ V SCROLLCLIPBOARD 



Format 



WM_VSCROLLCLIPBOARD 

lParaml: HWND hwndViewer; 

LOUINT (lParam2) : INT posScroll; 

HIUINT (lParam2) : INT codeScroll; 

Returns : OL 

Description 

These messages are sent to the clipboard owner win- 
dow when the clipboard contains a data handle for the 
CF_ OWNERDISPLAY format (i.e., the clipboard 
owner is responsible for displaying the clipboard con- 
tents) and an event occurs in the clipboard 
application’s horizontal scroll bar. 

lParaml contains a handle to the clipboard applica- 
tion window. 

HIUINT(lParam2) contains one of the SB_* scroll bar 
codes as defined in the "Scroll Bar Controls" section. 

Except for SB_ THUMBPOSITION, LOUINT(lParam2) 
contains 0. 

Notes The clipboard owner should use WinlnvalidateRect or 
repaint as desired. The scroll bar position should also 
be reset. 



4.1.19.5 Clipboard Viewer Functions 



WinSetCl ipbrdViewer 

Format 
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Description 

This function sets the current clipboard viewer win- 
dow to hwndViewer. It returns the previous clipboard 
viewer, or NULL if there was none. The returned win- 
dow handle is not locked. 



WinQueryClipbrdViewer 



Format 



HWND WinQueryClipbrdViewer (hab, fLock) 

BOOL fLock ; 

HAB hab; 

Description 

This function returns the current Clipboard viewer 
window or NULL if there isn’t one. If fLock is TRUE, 
the window is locked before returning. If fLock is 
FALSE, the window is not locked by this call (it may 
already have been locked by some other call). 



WM_ DRAW CLIPBOARD 



Format 



WM_DRAWCL I P BO ARD 
lParaml: OL 

lParam2 : OL 

Returns : OL 

Description 

This message is sent to the clipboard viewer window 
whenever the contents of the clipboard change. 



4.1.19.6 Clipboard Examples 

4-1 .19.6.1 Cutting or Copying; no delayed rendering 

1. Open the clipboard with WinOpenClipbrd(). 

2. Call WinEmptyClipbrdQ to delete the previous contents of the clip- 
board. 

3. Using the current selection, create clipboard data handle in the desired 
format(s) and place each handle into the clipboard with Win- 
SetClipbrdDataQ. Once placed in the clipboard, the handles are no 
longer valid, ana must not be used again by the application. 
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4. After all of the desired formats have been added to the clipboard, close 
the clipboard with WinCloseClipbrdQ. 



4-1.19.6.2 Cutting or Copying with delayed rendering 

1. Open the clipboard with WinOpenClipbrd(). 

2. Call WinEmptyClipbrdQ to delete the previous contents of the clip- 
board 

3. Call WinSetClipbrdOwnerQ to set the ownership of the clipboard 

4. Call WinSetClipbrdDataQ with the desired format values and a NULL 
data handle. 

5. If desired, create data in any of the standard display formats, and put 
the handles in the clipboard with WinSetClipbrdDataQ. 

6. Close the clipboard. 

7. When a WM_ RENDERFORMAT message is recieved by the clipboard 
owner window, the data of the requested format should be rendered 
and placed into the window with WinSetClipbrdDataQ. It is not 
necessary to open the clipboard when processing the 

WM_ RENDERFORMAT message. 

8 . I f a WM_ PAINTCLIPBO ARD, WM_ SIZECLIPBOARD, 

WM_ HSCROLLCLIPBOARD or WM_ VSCROLLCLIPBOARD mes- 
saged is receive, carry out the requested function to repaint the clip- 
board. 

9. If a WM_ DESTROY CLIPBOARD message is received, free up any 
data in the clipboard. 



4-1.19.6.3 Pasting 

1. Open the clipboard with WinOpenClipbrdQ. 

2. Call WinQueryClipbrdDataQ with the format that is most con- 
veniently handled by the application doing the Paste. If NULL is 
returned to indicate that data in that format is not available, try any 
other formats that the application knows how to Paste. 

3. If a handle is obtained with WinQueryClipbrdDataQ, it may be used as 
long as the clipboard remains open. Once the clipboard is closed, the 
handle may be deleted. Since leaving the clipboard open for long 
periods of time may prevent other applications from accessing the clip- 
board, it’s a good idea to make a copy of the clipboard data, and then 
close the clipboard. 

4. When finished with the clipboard data handle, close the clipboard with 
WinCloseClipbrdQ. 
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4.1.20 Rectangle Functions 



4.1.20.1 Data structures 

This section documents the rectangle and point utility functions. The rec- 
tangle structure is: 

typedef struct { 

I NT xLeft; 

I NT dummy 1; 

I NT y Bottom; 

I NT dummy 2; 

I NT xRight; 

I NT dummy 3; 

I NT yTop; 

I NT dummy4 ; 

> RECT; 

typedef RECT FAR *LPRECT; 

The point structure is: 

typedef struct { 

INT x; 

I NT dummy 1; 

INT y; 

INT dummy 2; 

> POINT 

A POINT structure describes a window coordinate point. A RECT struc- 
ture describes a rectangular area in the window coordinate space: it is 
stored as an array of 2 points, the first point being the bottom left corner 
of the rectangle, and the second point being the top right corner. 

An empty rectangle is a rectangle that has no area: the right coordinate is 
less than or equal to the left, top is less than or equal to the bottom. 

The rectangle routines assume that coordinates increase as you go up or to 
the right. 

Logically speaking, the right and top coordinates of a rectangle are one 
greater than the last coordinate included in the rectangle. Also, some of 
the rectangle routines assume that coordinates used are in window coordi- 
nates, where left and bottom most coordinates are smaller than the right 
or top coordinates. 

To calculate the dimensions in pixels: 

cy = rc.yTop - rc.yBottom 
cx = rc. xRight - rc. xLeft; 

To determine whether a coordinate falls inside a rectangle: 
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f Inside = ( (rc.xLeft <= x &&. x < rc.xRight) 

&& (rc.yBottom <= x && y < rc.yTop) ) ; 

Note that the comparisons to right and bottom are done with "less than". 

When passed to a WinXXX function, the values of dummyl..3 are not 
significant. The system may alter the values of these fields, however. 

These structures are very similar to the GRECT and GPOINT structures, 
except that only the lower 16 bits of the values are significant. A RECT 
or POINT can be converted to a GRECT or GPOINT by simply sign 
extending the 16 bit fields into the hi-order 16 bits. 

The functions WinMakeGRect and WinMakeGPoint convert RECT and 
POINT structures to GRECTs and GPOINTs respectively, by sign extend- 
ing the significant fields into the dummy fields. 

Any function that returns a rectangle or point (WinGetWindowRect, Win- 
BeginPaint, etc.) always sign extends the significant fields into the dummy 
fields; that is, the returned structures can be used as GRECTs or 
GPOINTs. 



4.1.20.2 Rectangle routines 



WinSetRect 



Format 



void WinSetRect (hab, lprc, left, bottom, 
right, top) 

LPRECT lprc; 

INT left; 

I NT top; 

INT right; 

INT bottom; 

HAB hab; 

Description 

This function fills the rectangle pointed to by lprc with 
the passed coordinates. This routine is equivalent to 
assigning the left, top, right, and bottom arguments to 
the appropriate fields of *lprc. 



WinlsRec tEmpty 

Format 
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Description 

This function returns TRUE if *lprc is an empty rec- 
tangle, FALSE otherwise. An empty rectangle is one 
that has no area: right is less than or equal to left, 
bottom is less than or equal to top. 

Notes This function works only if the top and left coordi- 
nates of *lprc are less than or equal to the bottom and 
right coordinates. 



WinCopyRect 



Format 



void WinCopyRect (hab , IprcDest, IprcSrc) 
LPRECT IprcDest; 

LPRECT IprcSrc; 

HAB hab; 

Description 

This function copies the rectangle from *lprcSrc to 
*lprcDest. 



WinEqualRect 



Format 



BOOL WinEqualRect (hab, lprcl, lprc2) 

LPRECT lprcl; 

LPRECT lprc2 ; 

HAB hab; 

Description 

This function returns TRUE if *lprcl and *lprc2 are 
identical, FALSE otherwise. 



WinSetRectEmpty 



Format 



void WinSetRectEmpty (hab , lprc) 

LPRECT lprc; 

HAB hab; 

Description 

This function sets *lprc to an empty rectangle by set- 
ting each field to 0. Equivalent to WinSetRect(lprc, 0, 
0 , 0 , 0). 
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WinOffsetRect 



Format 



void WinOffsetRect (hab, lprc, cx, cy) 

LPRECT lprc; 

I NT cx; 

I NT cy; 

HAB hab; 

Description 

This function offsets the coordinates of *lprc by 
adding cx to both the left and right coordinates, and 
cy to both the top and bottom coordinates. 



WinlnflateRect 



Format 



VOID WinlnflateRect (hab, lprc, cx, cy) 

LPRECT lprc; 

I NT cx; 

I NT cy; 

HAB hab; 

Description 

This function expands the given rectangle by cx hor- 
izontally and cy vertically on all sides. If cx or cy is 
negative, the rectangle is inset, cx is subtracted from 
the left and added to the right, and cy is subtracted 
from the bottom and added to the top. 



WinPtlnRect 



Format 



BOOL WinPtlnRect (hab, lprc, pt) 

LPRECT lprc; 

POINT pt; 

HAB hab; 

Description 

This function returns TRUE if pt falls inside of *lprc. 

Notes This function works only if the bottom and left coordi- 
nates of *lprc are less than or equal to the top and 
right coordinates. 
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WinlntersectRect 



Format 



BOOL WinlntersectRect (hab, IprcDest, 

IprcSrcl, lprcSrc2) 

LPRECT IprcDest; 

LPRECT IprcSrcl; 

LPRECT lprcSrc2; 

HAB hab; 

Description 

Calculates the intersection between *lprcSrcl and 
*lprcSrc2, returning the resulting rectangle in 
*lprcDest. Returns TRUE if *lprcSrcl intersects 
*lprcSrc2, FALSE otherwise. If there is no intersec- 
tion, an empty rectangle is returned in *lprcDest. 

Notes This function works only if the bottom and left coordi- 
nates of both *lprcSrcl and *lprcSrc2 are less than or 
equal to the top and right coordinates . 



WinUnionRect 



Format 



BOOL WinUnionRect (hab, IprcDest, 

IprcSrcl, lprcSrc2) 

LPRECT IprcDest; 

LPRECT IprcSrcl; 

LPRECT lprcSrc2; 

HAB hab; 

Description 

This function calculates a rectangle that bounds 
*lprcSrcl and *lprcSrc2, returning the result in 
*lprcDest. If either *lprcSrcl or *lprcSrc2 are NULL, 
then the other rectangle is returned. Returns TRUE if 
*lprcDest is a non-empty rectangle, FALSE otherwise. 

Notes This function works only if the bottom and left coordi- 
nates of both *lprcSrcl and *lprcSrc2 are less than or 
equal to the top and right coordinates . 



WinSubtractRect 



Format 



BOOL WinSubtractRect (hab, IprcDest, 
lprcl, lprc2) 

LPRECT IprcDest; 
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LPRECT IprcSrcl ; 

LPRECT lprcSrc2 ; 

HAB hab; 

Description 

This function subtracts *lprc2 from *lprcl, returing 
the result in *lprcDest. Returns TRUE if *lprcDest is 
empty, FALSE otherwise. 

Notes Subtracting one rectangle from another may not 

always result in a rectangular area; in this case Sub- 
tractRect will return *lprcl in *lprcDest. For this rea- 
son, SubtractRect provides only an approximation of 
subtraction. However, the area described by *lprcDest 
will always be greater than or equal to the '’true" 
result of the subtraction. 

You can use the GPICombineRgnQ function to calcu- 
late the true result of the subtraction of two rectangu- 
lar areas. SubtractRectQ is much faster, however. 

This function works only if the bottom and left coordi- 
nates of both *lprcSrcl and *lprcSrc2 are less than or 
equal to the top and right coordinates . 



WinMakeGRect 



Format 



BOOL WinMakeGRect (lprc) 

LPRECT lprc; 

Description 

This function converts the RECT structure referenced 
by lprc into a GRECT structure. 

Returns TRUE if the conversion is sucessful, FALSE 
otherwise. 



WinMakeGPoint 



Format 



BOOL WinMakeGPoint (lppt) 

LPPOINT lppt; 

Description 

This function converts the POINT structure referenced 
by lprc into a GPOINT structure. 

Returns TRUE if the conversion is sucessful, FALSE 
otherwise. 
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4.1.21 Presentation Manager Resources 



WinLoadString 



Format 



int WinLoadString (hab, idModule, idString, 
IpszBuffer, cchBuf ferMax) 

HAB hab; 

UINT idModule; 

UINT idString; 

LPSTR IpszBuffer; 
int cchBuf ferMax; 

Description 

This function loads a string resource identified by 
idString from the executable file associated with 
module idModule which is returned by the DOS 
DosLoadModule call. The function copies the string 
into the buffer pointed to by lpBuffer, and appends a 
terminating null character. Returns the size of the the 
string copied into IpszBuffer, which is no larger than 
(cchBufferMax - 1). 

If idModule is NULL, a bitmap from the application 
resource file is loadd. Otherwise, idModule is the 
module handle of a dynlink library containingthe bit- 
map resource. 

For loading bitmaps, see WinLoadBitmap. 



4.1.22 Command Key Accelerators 

Accelerators are keyboard keystrokes which can be used to invoke com- 
mands directly. The normal way in which this is done is to convert the 
keystrokes into WM_ COMMAND, WM_ SYSCOMMAND or WM_HELP 
messages before they are received by the application, during the 
WinGetMsg or WinPeekMsg functions. This can allow single keystrokes 
to appear the same as selecting an item off a menu, to the user and the 
application alike. 

The Accelerator Table is used to define which keystrokes are treated as 
accelerators and the Commands they are translated into. 

The WinSet/GetAccelTableQ functions are used to set and get the 
accelerator table that is used implicitly by the WinGetMsgQ and Win- 
PeekMsgQ functions. A WM_ SYSCOMMAND, WM_ COMMAND or 
WM—HELP message is sent, depending on whether or not the SYSCOM- 
MAND or HELP flags are set in the accelerator option definition. 
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Note that the Accelerator tables are used in a two- level fashion. There is 
a table which operates on a per-input-queue basis and also one which 
works on a per-active-window basis. Both are used in succession during 
message processing in WinGetMsg and WinPeekMsg. This two level struc- 
ture allows for some accelerators which are global across all windows 
(Fl=Help, for example) as well as accelerators which are closely allied to 
the menu of a particular window. 

Translation within WinGetMsg is done with the active window’s accelera- 
tor table first and subsequently with the queue table. This implies that 
entries in the queue table can be overridden by entries in the active win- 
dow table. 

The following is the structure of an accelerator table: 

typedef struct tagACCELTABLE {_ 

UINT cAccel; 

UINT codepage; 

ACCEL rgaccel (cEntries) ; 

> ACCELTABLE ; 

• cAccel is the count of accelerators in the table. 

• codepage is the code page assumed by all AF-CHAR entries (only code 
points are tied to a particular code page, scan codes and virtual keys 
are not). 

typedef struct tagACCEL { 

UINT rgf ; 

UINT key; 

UINT cmd; 

> ACCEL; 

• rgf contains a combination of the following flags: 



AF-CHAR 

key contains a codepoint (translated character) (codepoint 
value is in codepage identified in ACCELTABLE structure 
above). 

AF-VIRTUALKEY 

key contains a virtual key value 

AF-SCANCODE 

key contains a scan code value 

NOTE - the three values above have the same value as their 
KC_* counterparts. 

AF_ SHIFT 

Shift key must be down 

AF_ CONTROL 

Control key must be down 
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AF_ALT 

Alt key must be down 
AF_ SYSCOMMAND 

Produce WM_ SYSCOMMAND instead of WM_ COMMAND 
AF-HELP 

Produce \VM_HELP instead of WM_ COMMAND 

• key contains the virtual key, scan code, or code point value (depending 
on the contents of rgf). 

• cmd contains the command ID value to be placed in lParaml of the 
resultant WM_ COMMAND, WM_ SYSCOMMAND, or WM-HELP 
message. 

typedef { 

ULONG HACCEL; 

> 



WinLoadAccelTable 



Format 



HACCEL WinLoadAccelTable (hab, idModule, idAccelTable) 
HAB 

UINT idModule; 

UINT idAccelTable; 

Description 

Loads an accelerator table identified by idModule, 
which is returned by th DOS DosLoadModule call, and 
idAccelTable, returning the handle of the accelerator 
table. 

Note that this function will return a different hAccel 
value when called twice in succession with the same 
parameter values. 



WinCreateAccelTable 



Format 



HACCEL haccel = WinCreateAccelTable (hab, IpAccel) 
HAB hab; 

ACCELTABLE FAR * IpAccel; 

Description 

Given a pointer to an accelerator table in memory, 

IpAccel, this function creates an accelerator table han- 
dle. IpAccel points to an ACCELTABLE structure. 

Note that this function will return a different hAccel 
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value when called twice in succession with the same 
parameter values. 



WinDestroyAccelTable 



Format 



BOOL fDestroyed = WinDestroyAccelTable (haccel) 
HACCEL haccel; 

Description 

This function destroys an accelerator table, returning 
TRUE if successful, FALSE otherwise. 



Win Cop y AccelTable 



Format 



WORD cbCopied = WinCopyAccelTable (haccel , IpAccel, 
cbCopyMax) 

HACCEL haccel; 

ACCELTABLE FAR * IpAccel; 

WORD cbCopyMax; 

Description 

This function is used to either obtain the accelerator 
table data corresponding to an accel table handle, or 
to determine the size of the table data. 

If the IpAccel pointer is not NULL, then up to cbCopy- 
Max bytes of the accelerator table data is copied to 
IpAccel. The actual number of bytes copied is 
returned. 

If IpAccel is NULL, then this function returns the size 
in bytes of the accelerator table handle; the cbCopy- 
Max parameter is ignored. 



WinTranslateAccel 



Format 



BOOL WinTranslateAccel (hab, hwnd, hAccel, lpqmsg) 
HAB hab; 

HWND hwnd; 

HACCEL hAccel; 

QMSG FAR *lpQmsg; 

Description 

This function translates the message pointed to by 
lpqmsg if it is a WM—CHAR message that is in the 
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accelerator table indicated by hAccel. The message is 
translated into a WM_ COMMAND, 

WM_ SYSCOMMAND or WM_HELP message, with 
hwnd identifying the destination window. Normally, 
this parameter should be a frame window handle. 

This function does not hilite menu items. 

If hAccel is NULL, the current accelerator table is 
assumed. 

WinTranslateAccelQ returns TRUE if the message 
matched an accelerator in the table. The message 
pointed to by lpqmsg is modified by WinTranslateAc- 
cel() if a match is found. 

If a menu item exists that matches the accelerator 
command value, and that item is disabled, the mes- 
sage at *lpqmsg is translated to a \VM_NULL mes- 
sage, rather than a WM_ COMMAND, 

WM_ SYSCOMMAND or WM-HELP message. If the 
command is a WM_ COMMAND or WM_ HELP, the 
menu child window of hwnd that has the FID_ MENU 
ID is searched; if WM_ SYSCOMMAND, the 
FID-SYSMENU child window is searched. 

It is possible to have accelerators that do not 
correspond to items in a menu. If the command value 
does not match any items in the menu, the message is 
STILL translated. 

Generally, applications do not have to call this func- 
tion. It is normally called automatically by 
WinGetMsg() and WinPeekMsgQ, when a WM-CHAR 
message is received, with the window handle of the 
active window as the first parameter. The standard 
frame window procedure always passes 
WM_ COMMAND messages to the FID_ CLIENT win- 
dow. Since the message is physically changed by Win- 
TranslateAccelQ, this implies that applications will 
not see the WM_ CHAR messages that resulted in 
WM_ COMMAND, WM_ SYSCOMMAND or 
WM-HELP messages. 



WinSetAccelTable 



Format 

BOOL FAR PASCAL WinSetAccelTable (hab , haccel , 
hwndFrame) 

HAB hab; 

HACCEL haccel; 

HWND hwndFrame; 
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Description 

This function is used to set either the window or queue 
accelerator table. If hwndFrame is NULL, then the 
queue accelerator table is set. Otherwise, the window 
accelerator table is set, by sending the 
WM_ SETACCELTABLE message to hwndFrame. 

If hAccel is NULL, the effect of this function is to 
remove any accelerator table in effect for the window 
or queue. 



WinQueryAccelT able 



Format 



HACCEL FAR PASCAL WinQueryAccelTable (hab, hwndFrame) 
HAB hab; 

HWND hwndFrame; 

Description 

This function is used to query either the window or 
queue accelerator table. If hwndFrame is NULL, then 
the queue accel table is returned. Otherwise, the win- 
dow accel table is returned, by sending the 
WM_ QUERYACCELTABLE message to hwndFrame. 



4.1.22.1 Accelerator Table Messages. 

The following messages are associated with Accelerator Table functions: 



WM_ SETACCELTABLE 



Format 



WM_SETACCELTABLE 

lParaml: HACCEL haccelNew 

Returns : BOOL f Success ; 

Description 

WM_ SETACCELTABLE is used to establish the win- 
dow accelerator table to be used for translation when 
the window is active. 



WM_ QUERYACCELTABLE 



Format 

WM_QUER Y ACCELTABLE 
Returns: HACCEL haccel; 
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Description 

WM_ QUERY ACCELT ABLE returns the accel table 
handle associated with the window, or NULL if none is 
associated. 



WM_ V ALID ATEACCEL 



Format 



WM_VAL I DATE ACCEL 
lParaml: LPQMSG lpqmsg; 

lParam2: OL; 

Returns: BOOL fValid; 

Description 

This message is sent by WinTranslateAcceleratorQ to 
the the window that will be the destination of the 
WM_ COMMAND/SYSCOMMAND/HELP message 
when a match is found in the accelerator table. 

lParaml points to a QMSG structure containing 
WM_ COMMAND/SYSCOMMAND/HELP message 
that will be returned. The message should return 
FALSE to indicate that the message is invalid and 
should not be passed on to the application, and TRUE 
to indicate that the message should be passed on to 
the app. 

This message is processed by the WC_ FRAME and 
WC_ DIALOG window procedures by seeing if the 
command exists in either the system or application 
menu (FID-SYSMENU and FID_MENU frame con- 
trols). If so, if the corresponding menu item is dis- 
abled, FALSE is returned. If the item is enabled, 
TRUE is returned. If the command does not exist in 
either menu, TRUE is returned. 

These messages are processed only by frame windows. 



4.1.22.2 Default Queue Accelerator Table. 

The default queue accelerator table contains entries for the following func- 
tions: 

• Enter menu mode (F2) 

• Bring up system menu 

• Help (Fl) 
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Switch application and switchlist keys are not part of this table. These 
are fixed by OS/2 and cannot be overriden in the accelerator tables. 



4.1.23 System Colors 

The System Colors are the colors that the system and applications use to 
color various parts of the user interface. These colors may be modified by 
the application 

The system color functions are used to get and change the system colors. 
The 



4.1.23.1 System Color Index Values 



System Color Indices 

Color Index Value 

SCLR- SCROLLBAR 

Scroll bar halftone area 

SCLR- BACKGROUND 
Desktop 

SCLR— ACTIVECAPTION 

Active window caption 

SCLR_ INACTIVECAPTION 

Inactive window caption 

SCLR- MENU 

Menu background 

SCLR- WINDOW 

Window background and thumb box 

SCLR- WINDOWFRAME 

Window border, caption text background 

SCLR— MENUTEXT 

Text in menus 

SCLR- WINDOWTEXT 
Text in windows 

SCLR— TITLETEXT 

Text in title bar, size box, scroll bar arrow box 
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4.1.23.2 System Color Routines 



Win Q u e ry SysColor 



Format 



ULONG WinQuerySysColor (hab, iColor) 

HAB hab; 
int iColor; 

Description 

This function returns the RGB color value that 
corresponds to the system color index indicated by 
iColor. iColor must be one of the SCLR_ * constants 
in the table below. 



WinSetSysColors 



Format 



void WinSetSysColors (hab. cColors, rgiColors, 
rglColorValu.es) 

HAB hab; 

int cColors; 

int far *rgiColors; 

ULONG far *rglColorValues; 

Description 

This functions changes one or more of the system 
colors. cColors is the count of the number of colors 
that are being changed, rgiColors is a far pointer to an 
array of system color indices, and rglColorValues is a 
far pointer to an array of ULONGs that represent 
RGB color values. Values in the rgiColors array must 
be SCLR_ * values from the table below. 

Notes WinSetSysColorsQ sends all top-level windows in the 
system a WM_ S YSCOLORCHANGE message to indi- 
cate that the colors have changed. When this message 
is received, applications that depend on the system 
colors can query the new color values with WinGetSys- 
ColorQ. 

After the WM_ SYSCOLORCHANGE messages are 
sent, all windows in the system are invalidated so that 
they will be redrawn with the new system colors. 

WinSetSysColorsQ does NOT write any system color 
changes to the WlN.INI file. 
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4.1.23.3 System Color Messages 



WM_ SYSCOLORCHANGE 



Format 



WM_SYSCOLORCHANGE 
lParaml : 0 

lParam2 : OL 

Returns : OL 

Description 

This message is sent to all top level windows when a 
change is made to the system colors with WinSetSys- 
ColorsQ. When this message is received, applications 
that depend on the system colors can query the new 
color values with WinGetSysColorQ. 

After the WM_ SYSCOLORCHANGE messages are 
sent, all windows in the system are invalidated so that 
they will be redrawn with the new system colors. 

4.1.24 System Information Functions 

This section describes functions used to retrieve and change system 
characteristics. 

The system value functions are used to get and change system information 
such as the height and width of the screen, dimensions of the various parts 
of a window, caret blink rate, etc. 



WinGetSysValue 



Format 



int WinGetSysValue (hwndDesktop, iSysVal) 

HWND hwndDesktop; 
int iSysVal; 

Description 

WinGetSysValue returns the system value indicated 
by iSysVal. hwndDesktop is the desktop window han- 
dle. iSysVal must be one of the SV_* constants in the 
table below. 

Notes NULL may be specified to obtain the system values for 
the screen device. 
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WinSetSysValue 



Format 



BOOL WinSetSysValue (hwndDesktop, iSysVal, value) 
HAB hab; 
int iSysVal; 
int value; 

HWND hwndDesktop; 

Description 

WinSetSysValue sets a new system value indicated by 
iSysVal to value, returning TRUE if successful, FALSE 
otherwise. iSysVal must be one of the SV_* constants 
in the table below. hwndDesktop is the desktop win- 
dow handle. 

Notes Not all SV_ values can be set with WinSetSysValue. 

NULL may be specified to obtain the system values for 
the screen device. 



4.1.24.1 System Value Constants 

Below is a table of the available system values, which can be used with the 
WinGetSysValue and WinSetSysValue functions. Dimension values are in 
pixel units, and time values are in milliseconds. Note that not all system 
values are settable with WinSetSysValue; those that are changeable are 
marked with an 



WinGetSysValue() Codes Settable? 

Meaning 

SV_ CXSCREEN 

Width of screen 

SV_ CYSCREEN 

Height of screen 

SV_ CXVSCROLL 

Vertical scroll bar width 

SV_ CYHSCROLL 

Horizontal scroll bar height 

SV_ CYVSCROLLARROW 

Height of vertical scroll bar arrow bitmaps 

SV_ CXHSCROLLARR.OW 

Width of horizontal scroll bar arrow bitmaps 
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SV_ CY CAPTION 

Height of caption 

SV_ CXBORDER 

Width of nominal-width border 

SV-CYBORDER 

Height of nominal-width border 

SV_ CXSIZEBORDER 

Width of sizing border 

SV-CYSIZEBORDER 

Height of sizing border 

SV_ CXDLGFRAME 

Width of dialog frame border 

SV_ CYDLGFRAME 

Height of dialog frame border 

SV_ CYVTHUMB 

Height of vertical scroll bar thumb 

SV_ CXHTHUMB 

Width of horizontal scroll bar thumb 

SV_ CXMINMAXBUTTON 

Width of Minimize/Maximize buttons 

SV-CYMINMAXBUTTON 

Height of Minimize/Maximize buttons 

SV_ CXSIZEBUTTON 

Width of size buttons 

SV_ CYSIZEBUTTON 

Height of size buttons 

SV_ CYMENU 

Single line menu height 

SV_ CXFULLSCREEN 

Client area width when window is full screen 

SV_ CYFULLSCREEN 

Client area height when full screen (excluding menu height) 

SV.CXJCON 

Icon width 

SV_ CYICON 

Icon height 

SV_ CXCURSOR 

Cursor width 
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SV-CYCURSOR 

Cursor height 

SV_ DEBUG 

TRUE if debugging version of system, FALSE otherwise 
SV-MOUSEPRESENT 

TRUE if system has mouse installed, FALSE otherwise 
SV_ FULLSCREEN 

TRUE if full screen window is present, FALSE otherwise 

SV_ CURSORLEVEL 

Cursor hide level (0 ==> visible) 

SV_ CTIMERS 

Count of available timers 

SV-SWAPBUTTON * 

TRUE if mouse buttons swapped. Normally, the mouse buttons 
are set for right-handed use. Setting this value changes them 
around for left-handed usage. 

If TRUE, WM_ LBUTTON* messages are returned when the 
user presses the right button, and WM_RBUTTON* messages 
are returned when the left button is pressed. Modifying this 
value affects the entire system. Applications should not nor- 
mally read or set this value. The user normally updates this 
value via the User Interface Shell to suit requirements. 

SV_ CARETBLINKTIME * 

Caret blink rate, in milliseconds 

SV_ DBLCLKTIME * 

Mouse doubleclick time, in milliseconds 

SV_ CXDBLCLK * 

Width of mouse doubleclick sensitive area 

SV_ CYDBLCLK * 

Height of mouse doubleclick sensitive area 

SV_ SBREPEATTIME * 

Scroll bar auto-repeat interval time, in milliseconds 

SV_ AL ARMFREQ * 

The frequency of the alarm signal generated by a call to Win- 
Beep() if its UINT parameter is Oxffff. 

S V_ ALARMDURATION * 

The duration of the alarm signal generated by a call to Win- 
Beep() if its UINT parameter is Oxffff. 

S V_ ARROW CURSOR 

Arrow cursor handle 
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SV_ IBEAMCURSOR 

Text I-Beam cursor handle 

SV_ HOURGLASSCURSOR 

Hourglass cursor handle 

SV_ UPARROWCURSOR 

Up-arrow cursor handle 

SV-SIZECURSOR 

Size cursor handle 

SV_ MOVECURSOR 

Move cursor handle 

4.1.25 Using Windows of Other Threads 

If an application is using a window handle of another thread or process, it 
is possible that the thread that owns the window might destroy the win- 
dow, thereby invalidating the window handle. Even worse, after the win- 
dow is destroyed, another thread may create a new window, that has the 
same window handle as the one previously destroyed. In this case, the 
application with the window handle of the invalid window handle now has 
a valid window handle of a completely different window. 

In order to prevent this problem, it is possible to "Lock" a window. A 
locked window cannot be destroyed; WinDestroyWindow() waits until the 
window is unlocked before proceeding. During this time, messages may be 
received from other applications, that may possibly involve the window 
being destroyed. 

Most functions that return a window handle have the option of returning 
that window handle locked or unlocked. If the function is being used in a 
context where it is guaranteed that the returned window handle is not of 
another thread, or the window handle is simply used for equality checking 
against NULL or a window of the current thread, it is not necessary to 
lock the window handle. If the window handle is used as an argument to 
other functions, or is sent messages, then the window handle must be 
locked. 

It is very important that a locked window handle be unlocked at some 
point. Otherwise, this may hang the application that owns the window 
when it attempts to destroy the window. 

To help guard against the possibility of an application leaving windows 
locked, the WinCheckWindowLockCountQ function can be called to check 
to see if any windows remain locked by the application. This function is 
typically called in an application’s main loop. This test is also made 
automatically when the application is terminated. 
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Windows should not be locked for indeterminate lengths of time. In order 
to use a window of another application for a long time, in order to store 
the handle in a global variable, etc., the window can be "Destroy 
Registered" When a destroy registered window is destroyed, all top level 
windows in the system are notified with a 

WM_ OTHER WINDOWDESTROYED message that the window has been 
destroyed. This message is sent before the window is actually destroyed. 
The idea is that the saved window handle may be invalidated by the appli- 
cation that saved the window handle. Before using a destroy registered 
window as an argument to a function or WinSendMsgQ, it should be 
locked as usual. 



4.1.25.1 Window Locking Functions 



WinLockWindow 



Format 



HWND WinLockWindow (hwnd) 

HWND hwnd; 

Description 

This function locks the specified window, preventing it 
from being destroyed. This function is used in con- 
junction with WinUnlock Window to ensure that a 
window handle of another application does not get 
destroyed while an application is using it. 

If WinDestroyWindowQ is called with a locked window 
handle, it is not actually destroyed until the window is 
unlocked. 

WinLockWindowQ returns hwnd if sucessful, or NULL 
if the window has been destroyed or is otherwise 
invalid. 

The window is marked as being locked by increment- 
ing a lock count. Therefore, the same window may be 
locked more than once by different applications. The 
number of WinUnlockWindowQ calls must match Win- 
Lock WindowQ calls. 



WinUnlockWindow 



Format 



UINT WinUnlockWindow (hwnd) 
HWND hwnd; 
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Description 

This routine unlocks a window. This is accomplished 
by decrementing the lock count that was incremented 
by WinLockWindow(). The window is not actually 
unlocked until this count reaches 0. 

Returns the lock count of the window after the unlock 
is performed. If the window was actually unlocked, 0 
is returned. 



WinGetWindowLockCount 



Format 



I NT WinGetWindowLockCount (hwnd) 

HWND hwnd; 

Description 

This function returns the lock count of the specified 
window, or 0 if the window is not locked. 

Since a window may be locked by another thread or 
process at any time, the value returned by this func- 
tion may also change at any time. 



WinCheckWindowLockCount 



Format 

VOID WinCheckWindowLockCount (hab, cLock) 

HAB hab; 

I NT cLock; 

Description 

In debugging versions of the system, this routine will 
produce an error message on a debugging terminal if 
the number of windows locked but not unlocked by the 
current thread is not equal to cLock. This function 
can be used to help ensure that applications don’t 
leave other application’s windows locked. 

In non-debug versions of the system, WinCheckWin- 
dowLockCount has no effect. 
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4.1.26 Window Destroy Registration 



WinRegisterWindowDestroy 



Format 



BOOL WinRegisterWindowDestroy (hwnd, fRegister) 
HWND hwnd; 

BOOL fRegister; 

Description 

This function provides a mechanism whereby an appli- 
cation will be notified when a window of another 
thread is destroyed. 

If fRegister is TRUE, this function registers the given 
window so that when it is destroyed, a 
WM-OTHERWINDOWDESTROYED message is 
broadcast to all top level windows of other tasks. 

Registering the window is accomplished by increment- 
ing a register count. If fRegister is FALSE, this rou- 
tine unregisters the window by decrementing the regis- 
ter count. The window is not actually unregistered 
until the count reaches 0. 



WM_ OTHERWINDOWDESTROYED 



Format 



WM_OTHERWI NDOWDE STRO YED 
lParaml: HWND hwndDestroyed; 

lParam2: OL 

Returns : OL 

Description 

This message is sent to all top-level windows when a 
window registered with WinRegisterWindowDestroyQ 
is destroyed. lParaml contains the window handle of 
the window being destroyed. The message is sent by 
WinDestroyWindowQ after the window has been hid- 
den, but before the window is actually destroyed. 

This message is non-queued. 
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4.1.27 System and Queue Hooks 

Presentation Manager provides a mechanism by which procedures written 
by an application programmer can get called when interesting things hap- 
pen in the system. Such procedures are called Hooks. These hooks allow 
things such as filtering of mouse & keyboard input before an application 
receives it. 

There are a number of places in the system where Hooks can be installed - 
ie. there are a number of different types of interesting events that can be 
hooked out and processed in some special ways. More than one procedure 
can be installed for a given type of event. In this case, the procdures are 
’chained’ together so that each event is first passed to one procedure and 
then to the next, and so on down the chain. This chain of procedures is 
called a Hook Chain 

Within a particular Hook Chain, the procedures are called in the order 
that they were installed. If a hook procedure returns FALSE, the next 
hook in the chain is called. If a hook procedure returns TRUE, then the 
next hook in the chain is not called. 

There are two kinds of hook chains: the System Chain and the Queue 
Chain. The system chain applies to all running Presentation Manager 
applications, but the queue chain applies only to the thread associated 
with the queue that has the hook installed. In this way, it is possible to 
install hooks that affect the entire system or just a particular thread. 

Procedures on a system chain (system hooks) may be called in the 
process/thread context of any running Presentation Manager application. 
Procedures on a queue chain (queue hooks) are called only in the context 
of the process/thread associated with the nooked queue. This has conse- 
quences for the way in which hook procedures are defined. 

System Hook procedures must be defined in library modules because it is 
not possible to call application module procedures from other applications. 
However, it is possible for an application to install one of its own pro- 
cedures as a queue hook into one of its own input queues without 
defining the procedure in a library module. 



WinSetHook 



Format 



BOOL WinSetHook (hab, hmq, iHook, lpfnHook, 
idModule) 

HAB hab; 

HMQ hmq; 

I NT iHook; 

FARPROC IpfnHook; 

UINT idModule; 
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Description 

Installs the lpfnHook procedure into the hook chain 
specified by iHook and hmq. idModule, returned by 
the DOS DosLoadModule call, is the module handle 
that contains the hook procedure. If idModule is 
NULL, the hook procedure is in the current module. 
iHook is a HK_* value from the table below that 
specifies which hook is being installed. Returns TRUE 
if successful, FALSE otherwise. 

If hmq is NULL, then the hook is installed in the sys- 
tem hook chain; otherwise, the hook is installed in the 
specified queue’s hook chain. For a given hook, queue 
hooks are always called before system hooks. System 
hooks are always added to the end of the chain, and 
queue hooks are added to the beginning of the chain. 

Notes Use WinQueryWindowULongQ to obtain the queue 
handle associated with a window handle. 

The value HMQ_ CURRENT can be used as the hmq 
parameter to indicate the current queue. 



WinReleaseHook 



Format 



BOOL WinReleaseHook (hab, hmq, iHook, lpfnHook, 
idModule) 

HAB hab; 

HMQ hmq; 

I NT iHook; 

FARPROC lpfnHook; 

UINT idModule; 

Description 

Unhooks the specified hook procedure from the hook 
chain specified by iHook and hmq. Returns TRUE if 
successful, FALSE otherwise. 

If hmq is NULL, then the hook is unhooked from the 
system hook chain; otherwise, the hook is removed 
from the specified queue’s hook chain. 

The value HMQ_ CURRENT can be used as the hmq 
parameter to indicate the current queue. 
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4.1.27.1 Hook example 

InitCode () 

{ 

WinSetHook (NULL, 

HK_EXAMPLE , 

WinHookProc) ; 

> 

BOOL EAR PASCAL ExampleHookProc (he, lParaml, lParam2) 

INT he; 

ULONG lParaml; 

ULONG lParam2 ; 

{ 

switch (he) { 
case 0: 

if (fProcessHook) { 

ExampleProcess (lParaml, lParam2) ; 

/* 

* Return TRUE to indicate that we've processed 

* the call, which will prevent the next guy on 

* the chain from being called. 

*/ 

return (TRUE) ; 

> 

break; 

> " 

/* 

* Return FALSE to indicate that we have not processed the 

* call to cause the message to be passed on to the next 

* link in the hook chain. 

*/ 

return (FALSE) ; 



4.1.27.2 Queue Hook codes 

Here is a list of the available hook codes. Complete documentation for 
each hook can be found elsewhere in this manual. 



Window Hook Codes 
HK_ INPUT 

Input hook: called when message is removed from app queue 
before msg is returned by WinGetMsg() or WinPeekMsg() 

HK_MSGFILTER 

Msg filter hook: called inside system mode loops 
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HK_ SENDMSG 

WinSendMsg hook: called as a message is being sent 
The following hooks may be installed only in the system hook chain: 



HK_ JOURNALRECORD 

Journal recording hook 

HK_ JOURNALPLAYBACK 

Journal playback hook 



4.1.27.3 HK_ INPUT hook 

The HK_ INPUT hook is called when messages are removed from an appli- 
cation queue, before being returned by WinGetMsgQ or WinPeekMsgQ. 



InputHook 



Format 



BOOL FAR PASCAL InputHook (lpQmsg) 

LPQMSG lpQmsg; 

Description 

lpQmsg is a pointer to a QMSG structure. This hook 
is called from within get/peekmsg just before return- 
ing to the application with the message that will be 
returned. There are no restrictions on calls that may 
be made at this time. 

If this hook returns TRUE, the message is not passed 
on to the application. If it returns FALSE, then the 
message is passed on. 



4.1.27.4 HK-MSGFILTER hook 

The HK_MSGFILTER hook is called inside any of the system mode loops, 
such as during size/move tracking, while a dialog box or menu is up, etc. 



MsgFilterHook 



Format 



BOOL EAR PASCAL MsgFilterHook ( msgf, lpQmsg) 
INT msgf; 

LPQMSG lpQmsg; 
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Description 

lpQmsg is a pointer to a QMSG structure, and msgf is 
a code indicating the context that the hook procedure 
is called in. The msgf code may be one of the follow- 
ing values: 

Message Filter Context Codes 
Context code 

MSGF_ DIALOGBOX 

DialogBoxQ mode loop 

MSGF_ MESSAGEBOX 

MsgBoxQ mode loop 

MSGF- MENU 

Menu tracking 

MSGF- MOVE 

Window movement tracking 

MSGF- SIZE 

Window size tracking 

MSGF- SCROLLBAR 

Scroll bar tracking 

MSGF- NEXTWINDOW 

Window enumeration mode loop 

If this hook procedure returns TRUE, the message has 
been processed by the hook and will not be processed 
by the mode loop code. If it returns false, the message 
will be processed by the mode loop code. 



CallMsgFilter 



Format 



BOOL Cal lMsgFilter (lpQmsg, msgf) 

LPQMSG lpQmsg; 

INT msgf; 

Description 

This function allows the application to call the 
HK-MSGFILTER hook procedure, msgf may be one of 
the standard MSGF_* values, or an application- 
specific code. WinCallMsgFilterQ returns TRUE if any 
of the message filter hooks returns TRUE, FALSE if 
they all return FALSE. 
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4.1.27.5 HK_SENDMSG hook 

typedef struct { 

ULONG lParam2 ; 

ULONG lParaml ; 

UINT msg; 

HWND hwnd; 

> SMHSTRUCT; 



SendMsgHook 



Format 



BOOL FAR PASCAL SendMsgHook (lpsmh, flnterTask) 
BOOL flnterTask; 

SMHSTRUCT FAR * lpsmh; 

Description 

The WinSendMsg hook is called whenever a window 
procedure is called via WinSendMsgQ or Win- 
DispatchMsg. flnterTask is TRUE if the message is an 
inter-task WinSendMsg, and FALSE if intra-task, 
lpsmh is a pointer to a SMHSTRUCT structure, 
defined above. 

The fields of the SMHSTRUCT contain the Win- 
SendMsg parameters. There is no special return value 
for the WinSendMsg hook. 



4.1.27.6 HK_HELP hook 



HelpHook 



Format 



BOOL FAR PASCAL HelpHook (context. idTopic, 
idSubTopic, IprcPosition) 

UINT context; 

UINT idTopic; 

UINT idSubTopic; 

LPRECT IprcPosition; 

Description 

This hook can be called directly by an application or 
in the default processing associated with windows, 
menus and message boxes: 

• WinDefWindowProc calls the HK-HELP hook 
with idTopic == window ID of window sent the 
message, idSubTopic == window ID of window 
with focus or Oxffff if no window has the focus, and 
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IprcPosition == window rect (in screen coordi- 
nates) of window with the focus or window sent 
the message if idSubTopic == Oxffff. 

• Menu code: calls the HK—HELP hook with idTopic 
== window ID of currently selected submenu, and 
idSubTopic == menu item ID of currently selected 
submenu item, or Oxffff if no item is selected. 
IprcPosition is the bounding rectangle of the 
selected item, or of the top level menu if idSubTo- 
pic == Oxffff. 

• Message Box code if WM_ HELP message is 

recieved while in a message box, then the help 
hook is called with idTopic == message box ID 
and idSubTopic == id of button, which is the 
same as message box return value 

corresponding to that button. IprcPosition is the 
bounding rectangle of the button. 

4.1.27.7 HK-JOURNALRECORD and 
HK_ JOURNALPLAYBACK hooks 



JournalRecordHook 



Format 



BOOL EAR PASCAL JournalRecordHook (lpqmsg) 
QMSG FAR * lpqmsg; 

Description 

lpqmsg points to a QMSG structure, which contains 
the message to be recorded. 

This hook is called AFTER raw input has been 
translated to WM_ CHAR or WM_ ?BUTTONDCLK 
messages, lpqmsg -> hwnd is also setup when the 
hook is called. 



JournalPlaybackHook 



Format 



BOOL FAR PASCAL JournalPlaybackHook (lpqmsg, fSkip) 
QMSG FAR * lpqmsg; 

BOOL fSkip ; 

Description 

lpqmsg points to a QMSG structure, where the mes- 
sage to be played back is to be returned. 
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When fSkip is FALSE, the journal playback hook 
returns the next message available. The same message 
should be returned each time, until it is skipped with a 
call with fSkip == TRUE (see below). 

The time at which the message will be ready to be 
played back should be returned in lpqmsg- >time. 

This time value may be greater than the current value. 
When this hook is called, the lpqmsg->time field is 
initialized to the current time, which can be used to 
determine whether the next message is ready or not. 
This value, rather than the result of WinGetCurrent- 
TimeQ, should be used for any delta calculations per- 
formed by the hook procedure. 

If fSkip is TRUE, then the journal playback hook 
should skip to the next message. The lpqmsg parame- 
ter is NULL in this case. 



WM_ QU EUESTATUS 
Format 



WM_QUEUE STATUS 

lParaml: queue status (result of WinQueryQueueStatus () i 

lParam2: OL 

Returns : OL 

Description 

The recording hook gets called by call to WinGet- 
QueueStatus if the results of WinGetQueueStatusQ 
changed since the last call. 

The playback hook should return these messages syn- 
chronized with everything else. 

Notes This message is only used fur journal recording and 
playback hooks. 



4-1.27.7.1 Notes on journal recording and playback 

• Although the record hook is called after raw input has been translated, 
it is necessary only to record the raw input data. For WM—CHAR 
msgs, only the KC_ flags, lpqmsg- >time, and the high order byte of 
lpqmsg- >lParaml (where the scan code is stored). In this case, 

KC_ CHAR should be 0. For mouse input messages, double click mes- 
sages may be recorded as simply single click messages. 

• On playback, it is not necessary to specify the lpqmsg- >hwnd or 
lpqmsg- >pt fields: these fields will always be filled in by the input 
code. 
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• Conversely, it is possible to play back only virtual keys and character 
codes, by not setting the KC-SCANCODE bit. In this case, applica- 
tions will recieve WM_CHAR messages that do not have the 
KC_SCANCODE bit set. 

• The journal recording hook is called after message translation occurs, 
but before the key is translated via the system or queue accelerator 
tables. 

• With double click messages, a problem can arise when messages are 
played back with the double click time different than when the mes- 
sages were recorded. The problem is that single clicks during record- 
ing may be interpreted as double clicks, or vice versa. Applications 
that make use of these hooks should probably save & restore the state 
of the system timing variables: double click time, cursor flash rate, 
repeat, etc., to ensure that no timing problems will arise in this 
fashion. 

• WinGetMsg/WinPeekMsg() may not be called inside either the journal 
record or playback hook. 

4.1.28 International Information 



4.1.28.1 Overview 

The functions described here deal with problems associated with different 
keyboards and code pages. 

Input translation depends upon the physical keyboard, and, for characters, 
on the code page in use. 

There are also functions which allow the application to translate between 
any two supported code pages. 

A number of national language facilities are provided by base DOS. 
Further ones described here supplement these. 



4.1.28.2 Input Translation 



4-1.28.2.1 Concepts 

Keyboard input is obtained in the form of messages received via 
WinGetMsg. 

A WM_ CHAR message is delivered for each keydown and keyup for all 
keys on the keyboard. Translation of the scan code received from the key- 
board is done by the WinGetMsg call that receives the keystroke. 
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WinGetMsg does not send a message for every typamatic repeat from the 
keyboard; it may buffer typamatic repeats into one or more messages. 

Each message contains a count, which is the number of typamatic repeats 
since the first keydown, or since the last WinGetMsg call. This count will 
begin at one for the first keydown. 

Keyboard data along with mouse data is buffered asynchronously into the 
Presentation Manager system queue. Keyboard data is removed from the 
system queue when the application that owns the input focus calls 
WinGetMsg or WinPeekMsg. Only one keyboard event is dequeued at a 
time. 

Translation occurs when the event is dequeued. The message obtained 
from WinGetMsg contains three separate fields that represent the key 
pressed: the hardware dependent scan code, the virtual key code and the 
codepoint or dead key. These are discussed below: 

• The virtual key (VKEY) concept is that there should be a virtual key 
code for each "word" (eg esc or Fl) on the keytops of the keyboard. 
Consistency requires tnat most applications should use the PC set of 
virtual keys built in to Presentation Manager, but applications with 
special requirements can define their own virtual key sets. An example 
of valid use of this capability is mainframe applications accessed via a 
terminal emulator. These use words such as clear, PAl, etc in contrast 
to PC applications which use esc, home etc. 

• The code point (CKEY) concept is that there should be a code point 
value for every key on the keyboard with a symbol on it. The code 
points can be either ASCII or EBCDIC and are country dependent. 
Effectively, each code point corresponds to a unique "glyph" that can 
appear on the screen. 

• Some keys with words on them (eg Enter) generate both a virtual key 
value and a code point. This is because the key does need to be 
treated as a function key in some applications, but also has a defined 
ASCII code point associated with it which some applications may 
prefer to use. 

• For CKEY values that correspond to dead keys (e.g. umlaut) 
WinGetMsg will identify these CKEYs with a special flag in the 
WM-CHAR message. It is the application’s responsibility to echo the 
dead key in the appropriate manner (i.e. without advancing the cur- 
sor). If the next CKEY after the dead key is a valid dead key combina- 
tion, then another flag will be set in the \VM_CHAR message to iden- 
tify the composite character. Again it is the application’s responsibil- 
ity to echo the character appropriately. There are three situations the 
application must deal with: 

• valid dead key combination should replace the dead key display 
with the new composite character 
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• invalid dead key combination (except the space character) should 
leave the dead key displayed, advance the cursor and display the 
new CKEY, followed by a beep. 

• dead key followed by a space should leave the dead key displayed 
and advance the cursor. 

• The valid set of dead keys and their combinations with other keys is 
defined for each supported code page. 



4-1.28.2.2 Keystroke Translation 

Presentation Manager keystroke translation provides full flexibility in 
remapping, support of country specific keyboard layouts, and support of 
EBCDIC and ASCII code pages. This is achieved by the use of three types 
of table which are described below: 

• The key to VKEY table (VKeyXLateTbl). This table generates virtual 
key codes based on the key pressed and the shift state. Presentation 
Manager supplies two tables of this type covering the PC VKEY set for 
the two physically different keyboards. 

• The key to Universal Glyph List (UGLl table(GlyphXLateTbl). (The 
UGL is is a list of all (non-DBCS) glyphs that can be generated by a 
Presentation Manager application using standard Presentation 
Manager facilities. All glyphs for all supported languages, plus the 
APL glyphs, are included in the UGL.) The key to UGL table is always 
used in conjunction with the UGL to CKEY table described below. It 
is uniquely defined by the layout of the keytops. Presentation Manager 
supplies tables of this type corresponding to all supported keyboard 
layouts. 

• The UGL to CKEY table (CharXLateTbl). This table is used in con- 
junction with the previous one. Presentation Manager supplies a table 
of this type for each supported code page. Also included in this table 
is the dead key table, which defines the valid dead keys for each code 
page and the valid dead key combinations. 

• The WinPeekMsg and WinGetMsg API calls control the translation 
process that generates the virtual key and character code values that 
are in the WM_ CHAR message. The translation process consists of 
the following steps: 

• Apply scan code/keyboard state to VKeyXLateTbl. Result is a vir- 
tual key. 

• Apply scan code/keyboard state to GlyphXLateTbl. Result is a 
glyph code. 

• Apply the glyph code to CharXLateTbl. Result is a character code, 
with appropriate dead key bits set. 
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The translation tables that control the above process are determined 
at boot time, based on the physical keyboard type and the values 
specified in CONFIG.SYS. 



4.1.28.3 String/Character Translation 

The functions in this section translate between any two of the code pages 
supported. 



WinCpTranslateString 



Format 



BOOL WinCpTranslateString (hab, cpSrc, IpSrc, 
cpDest:, lenDest, lpDest) 

HAB hab; 

LONG cpSrc; 

LPSTR IpSrc; 

LONG cpDest; 

LONG 1 enDest ; 

LPSTR lpDest; 

Description 

Translates a string from one code page to another. 
Both source and translated strings are null- 
terminated. 

The source string buffer pointed to by IpSrc is not 
altered. The translated string is written to the buffer 
pointed to by lpDest, up to a maximum of lenDest 
bytes. 

Returns 



FALSE Error; possible errors are: 

• Dissimilar code pages. No translation is 
possible. 

• Neither code page is recognized. 

• The source code page is not recognized. 

• The destination code page is not recog- 
nized. 

• The translated string is too long. Trun- 
cation has occurred. 

TRUE Successful translation of most if not all char- 
acters. Character substitution will occur for 

all untranslated characters. 
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WinCpTranslateChar 



Format 



UCHAR WinCpTranslateChar (hab, cpSrc, chSrc, 
cpDest) 

HAB hab; 

LONG cpSrc; 

UCHAR chSrc; 

LONG cpDest; 

Description 

Translates a character from one code page to another. 
Returns 



FALSE Error; possible errors are: 

• Dissimilar code pages. No translation is 
possible. 

• Neither code page is recognized. 

• The source code page is not recognized. 

• The destination code page is not recog- 
nized. 

• Translation requires more than one byte. 

TRUE The translated character in the destination 
code page. If an exact match was not possi- 
ble for this character between the specified 
code pages, the character will have been 
translated to a standard character. 



4.1.28.4 String functions 

This section describes the functions dealing with strings that depends on 
the current international informations set for the application. 

To order strings a two dimensionnal table must be used. Each rows con- 
sists of characters (eg: ’A’, ’A’ umlaut, ’a’, ’a’ umlaut, etc...). The charac- 
ters are ordered within a row (secondary order), but this ordering is secon- 
dary to the order of the row themselves (primary order). Here is an exam- 
ple of what could be a section of this table: 



A, A acute, A grave, A umlaut, a, a acute, a grave, a umlaut 

B, b 

C, C cedilla, c, c cedilla 

D, d 

E, E acute, E grave, E umlaut, e, e acute, e grave, e umlaut 
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This mechanism is not only usefull for accentuated strings ordering but 
also for case sensitive ordering. For example: 

’A’ < ’a’, 

’Be’ < 'be ' , but 
'Be' > ’ba’ 

In the third example the primary ordering of the 2nd characters (V and 
’a’) takes precedence over the secondary ordering of the lrst characters 
(’A’ and ’a’). In fact the secondary ordering is only considered when the 2 
strings are found equal following the primary ordering rule. By else when 
comparing strings with different lengthes the characters in the longer 
string that don’t have their counterpart are considered greater and the 
secondary ordering is ignored. For example: 

' a ' < ' ab ' and 
'a' < 'Ab'. 



WinCompareStrings 



Format 



int WinCompareStrings (idep, lpszl, lpsz2, fSecondary) 
UINT idep ; 

LPSTR lpszl; 

LPSTR lpsz 2; 

BOOL fSecondary; 

Description 

This function compares the two strings pointed to by 
lpszl and lpsz2, it takes into consideration primary 
and secondary order if fSecondary is TRUE, and only 
primary order if fSecondary is FALSE. 

It returns: 

0 if strings are equal, 

1 if string pointed to by lpszl is < string 
pointed to by lpsz2 

-1 if string pointed to by lpszl is > string 
pointed to by lpsz2 



WinlsAlpha 



Format 



BOOL WinlsAlpha (idep, lpsz) 
UINT idep; 

LPSTR lpsz; 
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Description 

This functions checks if the string pointed to by lpsz is 
only made of alphabetical character. It returns TRUE 
if this is the case, FALSE otherwise. 

Typically are valid any alphabetical characters with 
accents or marks like cedilla. Characters like space, 
comma, accents, etc... are not valid. 



WinLower 



Format 

UINT WinLower (idcp, lpsz) 

UINT idcp ; 

LPSTR lpsz; 

Description 

This function converts the given string to lower case, 
lpsz is a long pointer to a null-terminated string, that 
is updated in-place. 

The return value is the length of the converted string. 



WinUpper 



Format 



UINT WinUpper (idcp, lpsz) 

UINT idcp; 

LPSTR lpsz; 

Description 

This function converts a string or a character to upper 
case, lpsz is a long pointer to a null-terminated string, 
that is updated in-place. 

The return value is the length of the converted string. 



WinUpperChar 

Format 



UINT WinUpperChar (idcp, wlnchar) ; 

UINT idcp; 

UINT wlnchar; 

Description 

This function converts a character in wlnchar to upper 
case. 

The return value is the converted character, or zero if 
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an invalid character was detected. 



WinLowerChar 


Format 


UINT WinLowerChar (idcp, wlnchar); 
UINT idcp; 

UINT wlnchar; 


Description 

This function converts a character in wlnchar to lower 




case. 




The return value is the converted character, or zero if 
an invalid character was detected. 


WinNextChar 


Format 


LPSTR WinNextChar (idcp, lpCurrentChar) 
UINT idcp; 

LPSTR lpCurrentChar ; 


Description 

This function moves to the next character in a string. 
lpCurrentChar is a long pointer to a character in a 
null terminated string. 




The return value is a long pointer to the next charac- 
ter in the string, or if there is no next character, to the 
null character at the end of the string. 


Notes 


CPNext is used to move through strings whose charac- 
ters are two or more bytes each (for example, strings 
containing characters from a Japanese character set). 



WinPrevChar 



Format 



LPSTR WinPrevChar (idcp, IpStart, lpCurrentChar) 
UINT idcp; 

LPSTR IpStart; 

LPSTR lpCurrentChar; 

Description 

This function moves to the previous character in a 
string. IpStart is a long pointer to the beginning of 
the string. lpCurrentChar is a long pointer to a char- 
acter in a null terminated string. 
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The return value is a long pointer to the previous 
character in the string, or to the first character in the 
string if lpCurrentChar is equal to IpStart. 

Notes WinPrevCharQ is used to move through strings whose 
characters are two or more bytes each (for example, 
strings containing characters from a Japanese charac- 
ter set). 

4.1.28.5 Code Pages Available 



WinQuer yCpList 

Format 

LONG WinQueryCpList (hab, count, array) 

HAB hab; 

LONG count; 

LONG array [] ; 

Description 

This returns a list of the code pages currently avail- 
able. A maximum of count code pages is returned in 
array. 

Returns 



FA SE Error 

TRUE Number of code pages returned 

4.1.29 Miscellaneous 



WM_ SYSTEMERROR 



Format 



WM_SYSTEMERROR 
lParaml : 0 

lParam2 : OL 

Returns : OL 

Description 

This message is sent to all top-level windows when an 
out of memory system error occurs during Winlnitial- 
izeQ or WinCreateMsgQueueQ. The sh ell window 
notifies the user of the out of memory condition. 

If the window receiving the message is the frame 
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window, it repeats the message to the client window, 
the window with the window id of STDID- CLIENT. 
See "Window Frames". 
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LM_ SEARCHSTRING message, 296 
LM_ SELECTITEM message, 293 
LM_ SETITEMHANDLE message, 296 
LM_ SETITEMTEXT message, 294 
LM_ SETTOPINDEIX message, 292 
Locked Windows, 356 
LONG type, 41 
LPRECT type, 337 
LPSTR type, 41 



MENUITEM type, 307 
MM_ DELETEITEM message, 313 
MM_ ENDMENUMODE message, 312 
MM_ GETSELITEMLD message, 314 
MM_ INSERTITEM message, 312 
MM_ ITEMIDFROMPOSITION 
message, 317 

MM_ ITEMPOSITIONFROMID 
message, 316 

MM_ QUERYITEM message, 314 
MM_ QUERYITEMATTR message, 

317 

MM_ QUERYITEMCOUNT message, 
317 

MM_ QUERYITEMTEXT message, 315 
MM_ QUERYITEMTEXTLENGTH 
message, 315 

MM_ REMOVEITEM message, 313 
MM_ SELECTITEM message, 313 
MM_ SETITEM message, 316 
MM_ SETITEMATTR message, 318 
MM_ SETITEMHANDLE message, 315 
MM_ SETITEMTECXT message, 316 
MM_ STARTMENUMODE message, 
311 

Mnemonics., 306 
mouse 

button actions, 56 
pointer, 51 
selecting items, 52 



MsgFilterHook, 363 
multiple selection, 53 



ObjectWindows, 165 
online help, 91 
Orphaned Windows, 165 
Owned Window, 165 



parameter descriptor block, 114, 117, 
120, 147 

Parent Window, 163 
Parking-Lot, 60 
POINT type, 337 
pointer, 51 

Private Window Class, 161 
Program Handle array, 146 
Program Information Block, 113, 116, 
119, 146 

program titles, 110 
ProgramEntry, 111, 145, 148 
programs, starting with the Shell, 75 
Public Window Class, 161 



RECT type, 337 

restore size and position, 61 



SBM_ QUERYPOS message, 301 
SBM_ QUERYRANGE message, 301 
SBM—SETPOS message, 300 
SBM—SETSCROLLBAR message, 300 
selecting items, 52 
selection cursor, 51 
SendMsgHook, 365 
SHANDLE type, 41 
shell 

general features, 50 

help index, 94 
Sibling Window, 163 
SMHSTRUCT type, 365 
starting OS/2 PM, 91 
starting programs, 75 
STARTUP, 75, 76 
STARTUP editor, 77 
stopping a task, 84 
Subclassing of Windows, 166 
Switch List Block, 134, 150 
switch list control block, 125, 128, 134, 
149, 150, 152 

Switch List entry definition, 134, 150, 
152 

SWP type, 188 

Sync Paint Window, 215 
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System Menu, 58 

SZM_ TRACKSIZE message, 246 



Task Manager, 81 

TBM_ QUERYSTATE message, 243 
TBM_ SETSTATE message, 244 
TBM_ TRACKMOVE message, 244 
terminating a task, 84 
titles, of programs, 110 
Top level windows, 163 
Top Window, 163 
tree window, 63 



UCHAR type, 41 
UINT type, 41 
ULONG type, 41 
Update Region, 214 



WC_ BUTTON, 278 
WC-EDIT, 284 
WC_ LISTBOX, 289 
WC-MINMAX, 246 
WC-SIZE, 245 
WC_ TITLEBAR, 243 
WinAlarm, 264 
WinBeginEnum Windows, 198 
WinBeginPaint, 218 
WinBeginPaint function, 215 
WinCalcFrameRect, 240 
WinCheckWindowLockCount, 358 
WinCloseClipbrd, 328 
WinCompareStrings, 373 
WinCopyAccelTable, 346 
WinCopyRect, 339 
WinCpTranslateChar, 372 
WinCpTranslateString, 371 
WinCreateAccelTable, 345 
WinCreateCaret, 318 
WinCreateCursor, 322 
WinCreateDlg, 255 
WinCreateFrameControls, 240 
WinCreateStdWindow, 238 
WinCreateStdWindowIndirect, 239 
WinCreateWindow, 171 
WinDestroyAccelTable, 346 
WinDestroyCaret, 320 
WinDestroyCursor, 323 
WinDestroyWindow, 173 
WinDismissDlg, 257 
WinDlgBox, 256 
window appearance, 57 
Window Coordinates, 162 
Window Descendants, 163 



Window Invalidation, 214 
Window Owner, 165 
Window Validation, 214 
windows 

changing size, 60 
controlling, 57 
maximizing, 59 
minimizing, 59 
moving, 61 

restoring size and position, 61 
using the System Menu, 58 
WinDrawBorder, 228 
WinDrawIcon, 228 
WinDrawText, 226 
WinEmptyClipbrd, 328 
WinEnableWindow, 175 
WinEnableWindowUpdate, 178 
WinEndEnumWindows, 198 
WinEndPaint, 218 
WinEndPaint function, 215 
WinEnumClipbrdFmts, 330 
WinEnumDlgltem, 260 
WinEnumWindow, 198 
WinEqualRect, 339 
WinExcludeUpdateRgn, 222 
WinFlash Window, 207 
WinFormatFrame, 241 
WinGetActiveWindow, 204 
WinGetCursorPos, 324 
WinGetPS, 216 
WinGetSysModalWindow, 208 
WinGetSysValue, 352 
WinGetWindowLockCount, 358 
WinHalftoneBitmap, 227 
WinlnflateRect, 340 
WinlntersectRect, 341 
WinlnvalidateRect, 219 
WinlnvalidateRgn, 219 
WinlnvertRect, 229 
WinlsAlpha, 373 
WinlsChild, 186 
WinlsRectEmpty, 338 
WinlsThread Active, 207 
Winls Window, 185 
WinlsWindowEnabled, 176 
WinlsWindowVisible, 179 
WinLoadAccelTable, 345 
WinLoadCursor, 322 
WinLoadDlg, 254 
WinLoadString, 343 
WinLockScreen, 223 
WinLockVisRgns, 224 
WinLockWindow, 357 
WinLower, 374 
WinLowerChar, 375 
WinMakeGPoint, 342 
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WinMakeGRect, 342 
WinMapDlgPoints, 259 
WinMapWindowPoints, 200 
WinMessageBox, 261 
WinMultWindowFromIDs, 184 
WinNextChar, 375 
WinOffsetRect, 340 
WinOpenClipbrd, 328 
WinOpenWindowDC, 217 
WinPrevChar, 375 
WinProcessDlg, 255 
WinProcessDlgMsg, 259 
WinPtlnRect, 340 
WinQueryAccelTable, 348 
WinQueryCaretlnfo, 321 
WinQueryClassInfo, 196 
WinQueryClassName, 170 
WinQueryClipbrdData, 330 
WinQueryClipbrdFmtlnfo, 331 
WinQueryClipbrdOwner, 329 
WinQueryClipbrdViewer, 335 
WinQueryCpList, 376 
WinQueryCursorlnfo, 325 
WinQueryDesktopWindow, 182 
WinQueryDlgltemlnt, 258 
WinQuerySysColor, 351 
WinQueryUpdateRect, 220 
WinQueryUpdateRgn, 221 
WinQueryWindow, 185 
WinQueryWindowParams, 181 
WinQueryWindowProcess, 186 
WinQueryWindowRect, 186 
WinQueryWindowText, 179 
WinQueryWindowTextLength, 180 
WinQueryWindowUInt, 201 
WinQueryWindowULong, 202 
WinRegisterClass, 169 
WinRegisterWindowDestroy, 359 
WinReleaseHook, 361 
WinReleasePS, 217 
WinRestrictCursor, 325 
WinScrollWindow, 224 
WinSendDlgltemMsg, 257 
WinSetAccelTable, 347 
WinSetActiveWindow, 203 
WinSetClipbrdData, 329 
WinSetClipbrdOwner, 329 
WinSetClipbrdViewer, 334 
WinSetCursor, 323 
WinSetCursorPos, 324 
WinSetDlgltemlnt, 258 
WinSetHook, 360 
WinSetMultWindowPos, 191 
WinSetOwner, 188 
WinSetParent, 187 
WinSetRect, 338 



WinSetRectEmpty, 339 
WinSetSysColors, 351 
WinSetSysModalWindow, 208 
WinSetSysValue, 353 
WinSetWindowParams, 181 
WinSetWindowPos, 188 
WinSetWindowText, 180 
WinSetWindowUInt, 202 
WinSetWindowULong, 202 
WinShowCaret, 320 
WinShowCursor, 323 
WinShowWindow, 177 
WinSubclassWindow, 196 
WinSubstituteStrings, 264 
WinSubtractRect, 341 
WinTranslateAccel, 346 
WinUnionRect, 341 
WinUnlock Window, 357 
WinUpdate Window, 221 
WinUpper, 374 
WinUpperChar, 374 
WinValidateRect, 220 
WinValidateRgn, 220 
WinWindowFromID, 184 
WinWindowFromPoint, 199 
WM_ ACTIVATE message, 205 
WM_ AC TIVAT ET HREAD message, 
206 

WM_ AD JUSTWINDOWRECT 
message, 270 

WM_ CALCVALIDRECTS message, 

193 

WM_ COMMAND message, 273 
WM_ CONTROL: Button Notification 
message, 281 

WM_ CONTROL message, 273 
WM_ CONTROLCURSOR message, 
275 

WM_ CONTROLHEAP message, 275 
WM_ CREATE message, 174 
WM_ DESTROY message, 175 
WM_ DESTROYCLIPBOARD 
message, 332 

WM_ DRAWCLIPBO ARD message, 

335 

WM_ DRAWITEM message, 290 
WM_ ENABLE message, 176 
W M_ ERASEB ACKGROUND message, 
234 

WM_ FORMATFRAME message, 233 
WM_HELP message, 274 
WM_HSCROLL message, 298 
WM_ HSCROLLCLIPBOARD message, 
334 

WM_ INITDIALOG message, 253 
WM_ MEASUREITEM message, 291 
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WM_MOVE message, 193 
WM_ OTHERWINDOWDESTROYED 
message, 359 

WM_ PAINT message, 215, 223 
WM_ PAINTCLIPBOARD message, 

332 

WM_ QUERYACCELTABLE message, 
348 

WM_ QUERYDLGCODE message, 272 
WM_ QUERYMI NN 1AX I NP O message, 
237 

\\Tvl_ QUERYMOVESIZEINFO 
message, 245 

WM_ QUERYTWINDOWPARAMS 
message, 183 

WM_ QUEUESTATUS, 367 
WM_ RENDERALLFMTS message, 

332 

WM_ RENDERFMT message, 331 
WM_ SETACCELTABLE message, 348 
WM_ SETITEMHEIGHT message, 295 
\VM_ SETWINDOWPARAMS 
message, 183 

WM_SHOW message, 179 
WM_ SIZE message, 192 
WM_ SIZECLIPBOARD message, 333 
WM_ SUBSTITUTESTRING message, 
265 

WM_ SYSCOLORCHANGE message, 
352 

WM_ SYSTEMERROR message, 376 
WM_ UPDATEFRAME message, 234 
WIVL VALID ATEACCEL message, 349 
WTVL VSCROLL message, 298 
WM_VSCROLLCLIPBOARD message, 
334 



xywinsize, 112, 133, 153 



Z-ordering, 59 




